API
Endpoints
Securely Store,
Share and Retrieve Your CyberFacts

SurfWatch API Endpoints

The SurfWatch API is a RESTful API that returns JSON data by default.

Authentication and authorization is based on the app-id and app-key header values required by all resources.

CyberFact Resources

CyberFact by ID

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/{cyberFactId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Path parameter Value
cyberFactId The ID of the CyberFact to retrieve.

Example Scenarios

Get CyberFact by ID

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/179852
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "cyberfact_polarity": -1,
  "cyberfact_score": 59,
  "cyberfact_id": 179852,
  "cyberfact_source_type_id": 3,
  "cyberfact_source_type": "Social Media",
  "industry_targets": [
    {
      "industry_target_id": 151543,
      "industry_target_description": "GHash.IO",
      "industry_id": -3,
      "industry_description": "Financials",
      "industry_group_id": 87,
      "industry_group_description": "Specialty Financials"
    }
  ],
  "tags": [
    {
      "tag_id": 3025,
      "tag": "distributed denial-of-service",
      "macro_tag_id": -301,
      "macro_tag": "Network Attack",
      "tag_super_type_id": 3,
      "tag_super_type": "Practice"
    },
    {
      "tag_id": 151660,
      "tag": "GHash.IO website",
      "macro_tag_id": -280,
      "macro_tag": "Websites",
      "tag_super_type_id": 2,
      "tag_super_type": "Target"
    },
    {
      "tag_id": 1153,
      "tag": "website downtime",
      "macro_tag_id": -508,
      "macro_tag": "Service Interruption",
      "tag_super_type_id": 5,
      "tag_super_type": "Effect"
    },
    {
      "tag_id": 17597,
      "tag": "unidentified hacker",
      "macro_tag_id": -105,
      "macro_tag": "Identity Unknown",
      "tag_super_type_id": 1,
      "tag_super_type": "Actor"
    }
  ],
  "publication_date": "2014-06-18T00:00:00.000Z",
  "cyberfact_source": "http://twitter.com/THEeCoreGroup/statuses/479198081829711872",
  "data_feed_ids": [
    -100,
    -3
  ]
}

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains a single CyberFact object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.
X-TOTAL-RESULTS A numeric value to indicate the total number of objects in the response array.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
today A boolean value used to set the date range of a query to today. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get CyberFacts

GET https://www.surfwatchlabs.com/api/v3/cyberFacts?startDate=2015-06-25&endDate=2015-06-25
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Get CyberFacts for Feed ID -4

GET https://www.surfwatchlabs.com/api/v3/cyberFacts?startDate=2015-06-25&endDate=2015-06-25&feedId=-4
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_polarity":-1,
    "cyberfact_score":68,
    "cyberfact_type_id": 2,
    "cyberfact_type": "Cyber Attack",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285028,
    "event_date":"2014-12-01T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":154989,
        "industry_target_description":"United States Office of Personnel Management",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":139,
        "industry_group_description":"Administration and Support",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":145981,
        "tag":"employee data",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":100588,
        "tag":"state-sponsored Chinese hacker",
        "macro_tag_id":-100,
        "macro_tag":"State-sponsored",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":122930,
        "tag":"unauthorized database access",
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":135300,
        "tag":"stolen employee data",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://netsecu.org/i/731f92af0",
    "data_feed_ids":[
      -100,
      -4
    ]
},
{
    "cyberfact_polarity":-1,
    "cyberfact_score":66,
    "cyberfact_type_id": 8,
    "cyberfact_type": "Data Breach",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285031,
    "event_date":"2015-06-23T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":100149,
        "industry_target_description":"National Security Agency (NSA)",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":153,
        "industry_group_description":"Military and Security Forces",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":11554,
        "tag":"leaked sensitive data",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":173651,
        "tag":"internet leak",
        "macro_tag_id":-305,
        "macro_tag":"Illicit Distribution",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":30604,
        "tag":"WikiLeaks",
        "macro_tag_id":-102,
        "macro_tag":"Hacktivist",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":182001,
        "tag":"sensitive documents",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"https://wikileaks.org/nsa-france/intercepts/#intercept4",
    "data_feed_ids":[
      -100,
      -4
    ]
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts by Cyber Tag

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/containingCyberTag/{cyberTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.
X-TOTAL-RESULTS A numeric value to indicate the total number of objects in the response array.

Request Parameters

Path parameter Value
cyberTagId The Cyber Tag ID the CyberFacts should contain.
Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
today A boolean value used to set the date range of a query to today. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get CyberFacts containing the Cyber Tag 'data breach'

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/containingCyberTag/2490?startDate=2015-06-25&endDate=2015-06-25
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_polarity":-1,
    "cyberfact_score":68,
    "cyberfact_type_id": 2,
    "cyberfact_type": "Cyber Attack",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285028,
    "event_date":"2014-12-01T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":154989,
        "industry_target_description":"United States Office of Personnel Management",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":139,
        "industry_group_description":"Administration and Support",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":145981,
        "tag":"employee data",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":100588,
        "tag":"state-sponsored Chinese hacker",
        "macro_tag_id":-100,
        "macro_tag":"State-sponsored",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":122930,
        "tag":"unauthorized database access",
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":135300,
        "tag":"stolen employee data",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://netsecu.org/i/731f92af0",
    "cyberfact_type":"Cyber Attack",
    "data_feed_ids":[
      -100,
      -4
    ]
},
{
    "cyberfact_polarity":-1,
    "cyberfact_score":66,
    "cyberfact_type_id": 8,
    "cyberfact_type": "Data Breach",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285031,
    "event_date":"2015-06-23T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":100149,
        "industry_target_description":"National Security Agency (NSA)",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":153,
        "industry_group_description":"Military and Security Forces",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":11554,
        "tag":"leaked sensitive data",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":173651,
        "tag":"internet leak",
        "macro_tag_id":-305,
        "macro_tag":"Illicit Distribution",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":30604,
        "tag":"WikiLeaks",
        "macro_tag_id":-102,
        "macro_tag":"Hacktivist",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":182001,
        "tag":"sensitive documents",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"https://wikileaks.org/nsa-france/intercepts/#intercept4",
    "cyberfact_type":"Data Breach",
    "data_feed_ids":[
      -100,
      -4
    ]
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts by Industry Target

An Industry Target identifies the organizations or individuals affected by a security incident. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/containingIndustryTargetTag/{industryTargetTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.
X-TOTAL-RESULTS A numeric value to indicate the total number of objects in the response array.

Request Parameters

Path parameter Value
industryTargetTagId The Industry Target ID the CyberFacts should contain.
Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
today A boolean value used to set the date range of a query to today. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get CyberFacts containing the Industry Target 'United States Office of Personnel Management'

POST https://www.surfwatchlabs.com/api/v3/cyberFacts/containingIndustryTargetTag/154989?startDate=2015-06-25&endDate=2015-06-25
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_polarity":-1,
    "cyberfact_score":68,
    "cyberfact_type_id": 2,
    "cyberfact_type": "Cyber Attack",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285028,
    "event_date":"2014-12-01T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":154989,
        "industry_target_description":"United States Office of Personnel Management",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":139,
        "industry_group_description":"Administration and Support",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":145981,
        "tag":"employee data",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":100588,
        "tag":"state-sponsored Chinese hacker",
        "macro_tag_id":-100,
        "macro_tag":"State-sponsored",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":122930,
        "tag":"unauthorized database access",
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":135300,
        "tag":"stolen employee data",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://netsecu.org/i/731f92af0",
    "cyberfact_type":"Cyber Attack",
    "data_feed_ids":[
      -100,
      -4
    ]
  },
  {
    "cyberfact_polarity":-1,
    "cyberfact_score":75,
    "cyberfact_type_id": 2,
    "cyberfact_type": "Cyber Attack",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "cyberfact_id":285024,
    "event_date":"2014-12-01T00:00:00.000Z",
    "industry_targets":[
      {
        "industry_target_id":154989,
        "industry_target_description":"United States Office of Personnel Management",
        "industry_id":-4,
        "industry_description":"Government",
        "industry_group_id":139,
        "industry_group_description":"Administration and Support",
        "industry_target_parent_id":52617,
        "industry_target_parent_description":"US government"
      }
    ],
    "tags":[
      {
        "tag_id":100588,
        "tag":"state-sponsored Chinese hacker",
        "macro_tag_id":-100,
        "macro_tag":"State-sponsored",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag_id":2490,
        "tag":"data breach",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":5594,
        "tag":"database compromised",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":122930,
        "tag":"unauthorized database access",
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":171361,
        "tag":"stolen family information",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":4830,
        "tag":"stolen personal information",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":135300,
        "tag":"stolen employee data",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":8383,
        "tag":"stolen social security numbers",
        "macro_tag_id":-522,
        "macro_tag":"Personal Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":145981,
        "tag":"employee data",
        "macro_tag_id":-211,
        "macro_tag":"Data",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":18689,
        "tag":"stolen financial information",
        "macro_tag_id":-528,
        "macro_tag":"Financial Information Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://www.washingtonpost.com/blogs/federal-eye/wp/2015/06/23/effort-to-improve-security-for-federal-employee-records-at-high-risk-of-failure-audit-finds/?postshare=9761435086620458",
    "cyberfact_type":"Cyber Attack",
    "data_feed_ids":[
      -100,
      -4
    ]
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts by Macro Tag

The Macro Tag is a more granular categorization of Cyber Tags, that exists under the Super Type in taxonomic rank. Therefore a Cyber Tag (lowest ranking categorization/most granular) is also categorized by a Macro Tag, and a Super Type. Therefore, CyberInsights can be produced at the Cyber Tag granularity, but also at the broader Macro Tag. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/containingMacroTag/{macroTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.
X-TOTAL-RESULTS A numeric value to indicate the total number of objects in the response array.

Request Parameters

Path parameter Value
macroTagId The Macro Tag ID the CyberFacts should contain.
Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
today A boolean value used to set the date range of a query to today. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get CyberFacts containing the Macro Tag 'Device Hijack'

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/containingMacroTag/-520?startDate=2016-10-01&endDate=2016-10-07
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_id": 1171276,
    "event_date": "2016-01-13T00:00:00.000Z",
    "cyberfact_polarity": -1,
    "cyberfact_score": 72,
    "cyberfact_type_id": 11,
    "cyberfact_type": "Illegal Trade",
    "cyberfact_source_type_id": 8,
    "cyberfact_source_type": "Cyber Risk Cloud",
    "data_feed_ids": [
      -101
    ],
    "industry_targets": [
      {
        "industry_target_id": 52441,
        "industry_target_description": "Microsoft Corp.",
        "industry_id": -7,
        "industry_description": "Information Technology",
        "industry_group_id": 118,
        "industry_group_description": "Software",
        "market": "NASDAQ"
      }
    ],
    "tags": [
      {
        "tag_id": 587274,
        "tag": "leaked FTP credentials",
        "macro_tag_id": -521,
        "macro_tag": "Credentials Stolen/Leaked",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 545533,
        "tag": "malicious code execution",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 203439,
        "tag": "Dream Market",
        "macro_tag_id": -112,
        "macro_tag": "Black Market",
        "tag_super_type_id": 1,
        "tag_super_type": "Actor"
      },
      {
        "tag_id": 18829,
        "tag": "Microsoft Windows",
        "macro_tag_id": -213,
        "macro_tag": "Operating Systems",
        "tag_super_type_id": 2,
        "tag_super_type": "Target"
      },
      {
        "tag_id": 40327,
        "tag": "malware trade",
        "macro_tag_id": -305,
        "macro_tag": "Illicit Distribution",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 208332,
        "tag": "debuyerking",
        "macro_tag_id": -111,
        "macro_tag": "Dark Web Actor",
        "tag_super_type_id": 1,
        "tag_super_type": "Actor"
      },
      {
        "tag_id": 100762,
        "tag": "keystroke logging",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 17540,
        "tag": "compromised device",
        "macro_tag_id": -520,
        "macro_tag": "Device Hijack",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 123487,
        "tag": "bot infection",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 289879,
        "tag": "Neutrino botnet",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      }
    ],
    "publication_date": "2016-10-03T08:09:39.260Z",
    "cyberfact_source": "https://www.surfwatchlabs.com/cyber-data/user_data/cyber_facts/-91313"
  },
  {
    "cyberfact_id": 1180191,
    "event_date": "2016-09-22T00:00:00.000Z",
    "cyberfact_polarity": 0,
    "cyberfact_score": 51,
    "cyberfact_type_id": 1,
    "cyberfact_type": "Advisory",
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media",
    "data_feed_ids": [
      -7,
      -100
    ],
    "industry_targets": [
      {
        "industry_target_id": 104548,
        "industry_target_description": "Linux Foundation (LF)",
        "industry_id": -7,
        "industry_description": "Information Technology",
        "industry_group_id": 118,
        "industry_group_description": "Software"
      }
    ],
    "tags": [
      {
        "tag_id": 5170,
        "tag": "malware distribution",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 197317,
        "tag": "Dofloo backdoor",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1163408,
        "tag": "IoT malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1103686,
        "tag": "Luabot malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1163412,
        "tag": "Ballpit worm",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 186826,
        "tag": "malware campaign analysis",
        "macro_tag_id": -311,
        "macro_tag": "Security Research",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1163231,
        "tag": "Routrem malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 117170,
        "tag": "Symantec Corporation",
        "macro_tag_id": -107,
        "macro_tag": "Information Security",
        "tag_super_type_id": 6,
        "tag_super_type": "Positive Actor"
      },
      {
        "tag_id": 176383,
        "tag": "malware campaign advisory",
        "macro_tag_id": -513,
        "macro_tag": "Threat Intelligence",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 175732,
        "tag": "XOR.DDoS flooding trojan",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1116478,
        "tag": "Gafgyt malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 296400,
        "tag": "Linux.Wifatch",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 1163413,
        "tag": "Aidra malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 969761,
        "tag": "Linux-based Internet of Things (IoT) devices",
        "macro_tag_id": -238,
        "macro_tag": "Consumer Electronics",
        "tag_super_type_id": 2,
        "tag_super_type": "Target"
      },
      {
        "tag_id": 199785,
        "tag": "Linux/Moose worm",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 185298,
        "tag": "launched DDoS attacks",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 1168437,
        "tag": "Kaiten malware",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 123487,
        "tag": "bot infection",
        "macro_tag_id": -509,
        "macro_tag": "Infected/Exploited Assets",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 114676,
        "tag": "Darlloz worm",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      },
      {
        "tag_id": 17540,
        "tag": "compromised device",
        "macro_tag_id": -520,
        "macro_tag": "Device Hijack",
        "tag_super_type_id": 5,
        "tag_super_type": "Effect"
      },
      {
        "tag_id": 1163410,
        "tag": "Pinscan trojan",
        "macro_tag_id": -300,
        "macro_tag": "Malware",
        "tag_super_type_id": 3,
        "tag_super_type": "Practice"
      }
    ],
    "publication_date": "2016-10-05T11:02:12.490Z",
    "cyberfact_source": "http://twitter.com/MalcolmIsaacs/statuses/783361203573776384"
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFact Polarities

The Polarity defines the disposition of a CyberFact, Cyber Tag, Industry Target, or Macro Tag. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/polarities

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get CyberFact Polarities

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/polarities
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "polarity":-1,
    "polarity_description":"Negative Influence CyberFacts outline an actual impact on specific individuals or entities experiencing real-world information security events."
  },
  {
    "polarity":0,
    "polarity_description":"Neutral Influence CyberFacts outline potential impact to broader groups and act as advisory or informational to default industry targets or clients of vendor products."
  },
  {
    "polarity":1,
    "polarity_description":"Positive Influence CyberFacts outline events, products and practices that benefit information security and availability."
  }
]

Payload Object

Key Value Type Value Description
polarity integer The unique identifier for the CyberFact Polarity.
cyberfact_polarity string The description of the CyberFact Polarity.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact Polarity objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFact Source Types

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/sourceTypes

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get CyberFact Source Types

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/sourceTypes
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_source_type_id": 1,
    "cyberfact_source_type": "Blog"
  },
  {
    "cyberfact_source_type_id": 2,
    "cyberfact_source_type": "Article"
  },
  {
    "cyberfact_source_type_id": 3,
    "cyberfact_source_type": "Social Media"
  }
]

Payload Object

Key Value Type Value Description
cyberfact_source_type_id integer The unique identifier for the CyberFact Source Type.
cyberfact_source_type string The description of the CyberFact Source Type.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact Source Type objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFact Types

The CyberFact Type is a high level categorization of what the CyberFact represents. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/types

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get CyberFact Types

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/types
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_type_id":1,
    "cyberfact_type":"Advisory",
    "cyberfact_type_description":"CyberFact outlines analysis and advisories for malicious activities that affect non-specific groups, vendor products, or data",
    "polarity":0
  },
  {
    "cyberfact_type_id":2,
    "cyberfact_type":"Cyber Attack",
    "cyberfact_type_description":"CyberFact outlines malicious actions against specific assets, data, groups or individuals",
    "polarity":-1
  }
]

Payload Object

Key Value Type Value Description
cyberfact_type_id integer The unique identifier for the CyberFact Type.
cyberfact_type string The short description of the CyberFact Type.
cyberfact_type_description string The description of the CyberFact Type.
polarity string, Polarity The CyberFact Polarity the CyberFact Type is associated with.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact Type objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts with Software Vulnerabilities

A software vulnerability is a weakness in a system (either by design or implementation) that could be exploited to gain unauthorized access to, or disrupt the stability, of a system. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/softwareVulnerabilities

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.
X-TOTAL-RESULTS A numeric value to indicate the total number of objects in the response array.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the today=true query option. Maximum: 90 day date range.
today A boolean value used to set the date range of a query to today. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get CyberFacts with Software Vulnerabilities

POST https://www.surfwatchlabs.com/api/v3/cyberFacts/softwareVulnerabilities
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "cyberfact_polarity":0,
    "cyberfact_score":61,
    "cyberfact_type_id": 6,
    "cyberfact_type": "Vulnerabilities",
    "cyberfact_source_type_id": 4,
    "cyberfact_source_type": "CVE",
    "cyberfact_id":285167,
    "event_date":"2015-06-22T15:59:00.070Z",
    "industry_targets":[
      {
        "industry_target_id":53388,
        "industry_target_description":"EMC Corp.",
        "industry_id":-7,
        "industry_description":"Information Technology",
        "industry_group_id":115,
        "industry_group_description":"Computer Hardware",
        "market":"NYSE"
      }
    ],
    "tags":[
      {
        "tag_id":148166,
        "tag":"vulnerability disclosed",
        "macro_tag_id":-513,
        "macro_tag":"Threat Intelligence",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":40304,
        "tag":"medium complexity vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":204684,
        "tag":"CVE-2015-0526",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40302,
        "tag":"network exploitable vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40311,
        "tag":"low integrity impact",
        "macro_tag_id":-509,
        "macro_tag":"Infected/Exploited Assets",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":151802,
        "tag":"cross-site scripting (XSS) vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":204685,
        "tag":"emc rsa_validation_manager 3.2",
        "macro_tag_id":-226,
        "macro_tag":"Management Software",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":127886,
        "tag":"National Institute of Standards and Technology (NIST)",
        "macro_tag_id":-600,
        "macro_tag":"Other Organizations",
        "tag_super_type_id":6,
        "tag_super_type":"Positive Actor"
      },
      {
        "tag_id":130198,
        "tag":"vulnerability reporting",
        "macro_tag_id":-311,
        "macro_tag":"Security Research",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40308,
        "tag":"no authentication instance vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2015-0526",
    "cyberfact_type":"Vulnerabilities",
    "data_feed_ids":[
      -7,
      -100
    ]
  },
  {
    "cyberfact_polarity":0,
    "cyberfact_score":68,
    "cyberfact_type_id": 6,
    "cyberfact_type": "Vulnerabilities",
    "cyberfact_source_type_id": 4,
    "cyberfact_source_type": "CVE",
    "cyberfact_id":285181,
    "event_date":"2015-06-23T14:59:08.180Z",
    "industry_targets":[
      {
        "industry_target_id":204762,
        "industry_target_description":"AudioShareScript.com",
        "industry_id":-7,
        "industry_description":"Information Technology",
        "industry_group_id":118,
        "industry_group_description":"Software"
      }
    ],
    "tags":[
      {
        "tag_id":158009,
        "tag":"code injection vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":130198,
        "tag":"vulnerability reporting",
        "macro_tag_id":-311,
        "macro_tag":"Security Research",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":204874,
        "tag":"CVE-2015-4726",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":148166,
        "tag":"vulnerability disclosed",
        "macro_tag_id":-513,
        "macro_tag":"Threat Intelligence",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":127886,
        "tag":"National Institute of Standards and Technology (NIST)",
        "macro_tag_id":-600,
        "macro_tag":"Other Organizations",
        "tag_super_type_id":6,
        "tag_super_type":"Positive Actor"
      },
      {
        "tag_id":40305,
        "tag":"low complexity vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40302,
        "tag":"network exploitable vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40309,
        "tag":"low confidentiality impact",
        "macro_tag_id":-500,
        "macro_tag":"Data Stolen/Leaked",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":204873,
        "tag":"audiosharescript audioshare 2.0.2",
        "macro_tag_id":-226,
        "macro_tag":"Management Software",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag_id":40311,
        "tag":"low integrity impact",
        "macro_tag_id":-509,
        "macro_tag":"Infected/Exploited Assets",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag_id":40308,
        "tag":"no authentication instance vulnerabilities",
        "macro_tag_id":-308,
        "macro_tag":"Software vulnerability exploit",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag_id":40313,
        "tag":"low availability impact",
        "macro_tag_id":-508,
        "macro_tag":"Service Interruption",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      }
    ],
    "publication_date":"2015-06-25T00:00:00.000Z",
    "cyberfact_source":"http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2015-4726",
    "cyberfact_type":"Vulnerabilities",
    "data_feed_ids":[
      -7,
      -100
    ]
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of CyberFact objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Tag Resources

Cyber Tag by ID

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/{cyberTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Path parameter Value
cyberTagId The ID of the Cyber Tag to retrieve.

Example Scenarios

Get Cyber Tag 'distributed denial-of-service' by ID

GET https://www.surfwatchlabs.com/api/v3/cyberTags/3025
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "tag_id": 3025,
  "tag": "distributed denial-of-service",
  "tag_polarity": -1,
  "macro_tag_id": -301,
  "macro_tag": "Network Attack",
  "tag_super_type_id": 3,
  "tag_super_type": "Practice"
}

Payload Object

Key Value Type Value Description
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains a single Cyber Tag object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Tags by Macro Tag

The Macro Tag is a more granular categorization of Cyber Tags, that exists under the Super Type in taxonomic rank. Therefore a Cyber Tag (lowest ranking categorization/most granular) is also categorized by a Macro Tag, and a Super Type. Therefore, CyberInsights can be produced at the Cyber Tag granularity, but also at the broader Macro Tag. View full definition.

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/containingMacroTag/{macroTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Path parameter Value
macroTagId The Macro Tag ID the Cyber Tags should contain.

Example Scenarios

Get Cyber Tags by Macro Tag 'Network Attack'

GET https://www.surfwatchlabs.com/api/v3/cyberTags/containingMacroTag/-301
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "tag_id": 146247,
    "tag": "DNS flood attack",
    "macro_tag_id": -301,
    "macro_tag": "Network Attack",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice"
  },
  {
    "tag_id": 1825,
    "tag": "denial-of-service attack",
    "macro_tag_id": -301,
    "macro_tag": "Network Attack",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice"
  },
  {
    "tag_id": 3158,
    "tag": "High Orbit Ion Cannon",
    "macro_tag_id": -301,
    "macro_tag": "Network Attack",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice"
  }
]

Payload Object

Key Value Type Value Description
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Cyber Tag objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Tag Macro Tags

The Macro Tag is a more granular categorization of Cyber Tags, that exists under the Super Type in taxonomic rank. Therefore a Cyber Tag (lowest ranking categorization/most granular) is also categorized by a Macro Tag, and a Super Type. Therefore, CyberInsights can be produced at the Cyber Tag granularity, but also at the broader Macro Tag. View full definition.

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/macroTags

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Cyber Tag Macro Tags

GET https://www.surfwatchlabs.com/api/v3/cyberTags/macroTags
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "macro_tag_id":-306,
    "macro_tag":"Insider Activity",
    "macro_tag_polarity":-1,
    "tag_super_type_id":3,
    "tag_super_type":"Practice"
  },
  {
    "macro_tag_id":-308,
    "macro_tag":"Software vulnerability exploit",
    "macro_tag_polarity":-1,
    "tag_super_type_id":3,
    "tag_super_type":"Practice"
  }
]

Payload Object

Key Value Type Value Description
macro_tag_id integer The unique identifier for the Macro Tag.
macro_tag string The textual description of the Macro Tag.
macro_tag_polarity integer, Polarity ID The polarity of the Macro Tag.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Cyber Tag Macro Tags objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Tag Macro Tag by ID

The Macro Tag is a more granular categorization of Cyber Tags, that exists under the Super Type in taxonomic rank. Therefore a Cyber Tag (lowest ranking categorization/most granular) is also categorized by a Macro Tag, and a Super Type. Therefore, CyberInsights can be produced at the Cyber Tag granularity, but also at the broader Macro Tag. View full definition.

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/macroTags/{macroTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Cyber Tag Macro Tag by ID

GET https://www.surfwatchlabs.com/api/v3/cyberTags/macroTags/-308
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "macro_tag_id":-308,
  "macro_tag":"Software vulnerability exploit",
  "macro_tag_polarity":-1,
  "tag_super_type_id":3,
  "tag_super_type":"Practice"
}

Payload Object

Key Value Type Value Description
macro_tag_id integer The unique identifier for the Macro Tag.
macro_tag string The textual description of the Macro Tag.
macro_tag_polarity integer, Polarity ID The polarity of the Macro Tag.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains a Cyber Tag Macro Tag object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Tag Super Types

Super Types are the broadest categorization of Cyber Tags in the taxonomy used to describe CyberFacts. Super Types may be one of Actor, Target, Effect and Practice. View full definition.

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/superTypes

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Cyber Tag Super Types

GET https://www.surfwatchlabs.com/api/v3/cyberTags/superTypes
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "tag_super_type_id":1,
    "tag_super_type":"Actor"
  },
  {
    "tag_super_type_id":2,
    "tag_super_type":"Target"
  }
]

Payload Object

Key Value Type Value Description
tag_super_type_id integer The unique identifier for the Tag Super Type.
tag_super_type string The textual description of the Tag Super Type.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Cyber Tag Super Types objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Search Cyber Tags

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/cyberTags/serach

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Search for Cyber Tags

GET https://www.surfwatchlabs.com/api/v3/cyberTags/search?q=dyre%20wolf
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "tag_id": 196139,
    "tag": "Dyre Wolf",
    "macro_tag_id": -102,
    "macro_tag": "Hacktivist",
    "tag_super_type_id": 1,
    "tag_super_type": "Actor",
    "tag_polarity": -1,
    "result_rank": 1
  },
  {
    "tag_id": 186383,
    "tag": "Dyre Wolf malware campaign",
    "macro_tag_id": -309,
    "macro_tag": "Hacking Operation",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_polarity": -1,
    "canonical_tag_id": 186383,
    "canonical_tag": "Dyre Wolf malware campaign",
    "canonical_tag_polarity": -1,
    "canonical_macro_tag_id": -309,
    "canonical_macro_tag": "Hacking Operation",
    "canonical_tag_super_type_id": 3,
    "canonical_tag_super_type": "Practice",
    "result_rank": 2
  },
  {
    "tag_id": 156152,
    "tag": "Dyre",
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_polarity": -1,
    "result_rank": 4
  }
]

Payload Object

Key Value Type Value Description
result_rank integer The search result match ranking.
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
canonical_tag_id long integer The unique identifier for the Canonical Cyber Tag. If the Cyber Tag represents the canonical form, then it will be the same as the Cyber Tag ID.
canonical_tag string The textual description of the Canonical Cyber Tag. This value may be different than the Cyber Tag, for example 'distributed denial-of-service' is the canonical form of 'ddos'.
canonical_tag_polarity integer, Polarity ID The polarity of the Canonical Cyber Tag.
canonical_macro_tag_id integer, Macro Tag ID The Macro Tag the Canonical Cyber Tag belongs to.
canonical_macro_tag string, Macro Tag The Macro Tag the Canonical Cyber Tag belongs to.
canonical_tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Canonical Cyber Tag belongs to.
canonical_tag_super_type string, Tag Super Type ID The Tag Super Type the Canonical Cyber Tag belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Cyber Tag Search Result objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Error Code Resources

Error Codes

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Receive Authentication Error

GET https://www.surfwatchlabs.com/api/v3/industries
Accept: application/json

Example Payload

{
  "user_message": "app-id was not provided",
  "error_instance_id": "e32556b8-037f-4353-9807-0504ccc9e245",
  "error_code": "authorization.appId.missing",
  "documentation_uri": "https://www.surfwatchlabs.com/api/v3/errorCodes/authorization.appId.missing"
}

Receive Invalid Long Error

GET https://www.surfwatchlabs.com/api/v3/cyberFacts/thirteen
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "user_message": "Unable to parse Long",
  "error_instance_id": "6fb3895b-e5f4-4be9-b48f-dbd8a81774d9",
  "error_code": "badRequest.long.invalid",
  "documentation_uri": "https://www.surfwatchlabs.com/api/v3/errorCodes/badRequest.long.invalid",
  "other_info": {
    "long": "thirteen",
    "min_value": "-9223372036854775808",
    "max_value": "9223372036854775807"
  }
}

Payload Object

Key Value Type Value Description
error_code string The unique URI identifier for the Error Code.
error_instance_id string The UUID of the Error Code response instance.
documentation_uri string The URI for a more descriptive explanation of the Error Code.
user_message string The short description of the Error Code.
other_info map of string key/values Additional information regarding the error.

Response Format

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Error Code

Endpoint

GET https://www.surfwatchlabs.com/api/v3/errorCodes/{errorCode}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only text/html is provided. No

Response Headers

Header parameter Value
Content-Type Only text/html is returned.

Request Parameters

Path parameter Value
errorCode The URI of the Error Code to explain.

Example Scenarios

Get Error Code

GET https://www.surfwatchlabs.com/api/v3/errorCodes/badRequest.long.invalid
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

<html>
  <body>
    <h1>Help Documentation</h1>
    <p>Error Code: badRequest.long.invalid</p>
    <p>The value that was provided was not able to be parsed as a long number. Should be of the format -?d+</p>
  </body>
</html>

Response Format

On success, the response status code is 200 OK and the response body contains a single Error Code explanation object in html format.

On an authentication error, the response status code is 403 Forbidden and the response body contains an error object.

On error, the response status code is an error code and the response body contains an error object.

Feed Resources

Feeds

Feeds are organizational units to contain SurfWatch Labs data and analytics. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/feeds

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Feeds

GET https://www.surfwatchlabs.com/api/v3/feeds
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "feed_id": -1,
    "feed_description": "Entertainment"
  },
  {
    "feed_id": -3,
    "feed_description": "Financials"
  },
  {
    "feed_id": -4,
    "feed_description": "Government"
  }
]

Payload Object

Key Value Type Value Description
feed_id integer The unique identifier for the Feed.
feed_description string The description of the Feed.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Feed objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Feed Risk Score Resources

Feed Risk Scores

Feed Risk Scores are the numeric ranking of the total risk or threats that exists in a Feed. The scores are based on historical CyberFacts that exist in the SurfWatch Labs data warehouse, and are on a 1-100 scale where '1' represents the least amount of risk and '100' the most. The score itself is made up of six different facets: Social Activity Score, Incident Volume Score, Actor Threat Score, Targeted Asset Score, Effect Impact Score, and Practice Impact Score. View full definition.

The Social Activity Score is a facet of the Feed Risk Score, and is the amount of social and/or media scrutiny that a particular Feed receives. While not a direct indicator of severity of events, it encompass the loss of reputation, brand and trust. The scores are on a 1-10 scale, where '1' represents the least amount of social activity and '10' the most. View full definition.

The Incident Volume Score is a facet of the Feed Risk Score, and are based on the number of unique reported cyber events that occur within a Feed. The scores are on a 1-10 scale, where '1' represents the least amount of volume and '10' the most. View full definition.

The Actor Threat Score is a facet of the Feed Risk Score, and is based on the Actors that are active within a Feed. As an example, if the majority of the Actors involved in a Feed are engage in industrial espionage or intellectual property theft, the threats and consequences of those individuals present a greater risk to a company within that Feed than a company in a Feed that is typically affected by political activism. The scores are on a 1-10 scale, where '1' represents the least threat and '10' the most. View full definition.

The Targeted Asset Scores is a facet of the Feed Risk Score, and reflect part of an Industry Targets infrastructure that can be exploited by an Actor's Practice. Examples of these include mobile devices, banking equipment, user accounts, medical equipment, cloud services, and blogs. The Targeted Asset Score is then based on the types of assets that are targeted in the infrastructure of entities that belong to a Feed. The scores are on a 1-10 scale, where '1' represents the least amount of targeted assets and '10' the most. View full definition.

The Effect Impact Score is a facet of the Feed Risk Score, and is based on the severity of Effects that are resulting from cyber events that occur within a Feed. A higher score means that the events in this Feed typically result in a more drastic Effects such as kinetic attack, financial loss, and service interruption. The scores are on a 1-10 scale, where '1' represents the least amount of impact of an Effect and '10' the most. View full definition.

The Practice Impact Score is a facet of the Feed Risk Score, and is a calculation of the Practice, or methods, typically employed on successful cyber event seen on entities grouped within the Feed. A higher score means that more nefarious methods are employed such as espionage, insider activity, and network intrusion. The scores are on a 1-10 scale, where '1' represents the least amount of impactful Practices and '10' the most. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/feedRiskScores

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Feed Risk scores

GET https://www.surfwatchlabs.com/api/v3/feedRiskScores?startDate=2015-06-25&endDate=2015-06-25
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day":"2015-06-25T00:00:00.000Z",
    "feed_id":-3,
    "feed_description":"Financials",
    "feed_risk":52.306,
    "feed_social_activity_percentile":0.387,
    "feed_social_activity_score":3.87,
    "feed_incident_volume_percentile":0.437,
    "feed_incident_volume_score":4.373,
    "feed_actor_threat_percentile":0.48,
    "feed_actor_threat_score":4.802,
    "feed_targeted_asset_percentile":0.611,
    "feed_targeted_asset_score":6.114,
    "feed_effect_impact_percentile":0.636,
    "feed_effect_impact_score":6.365,
    "feed_practice_percentile":0.559,
    "feed_practice_impact_score":5.589
  },
  {
    "analytic_day":"2015-06-25T00:00:00.000Z",
    "feed_id":-11,
    "feed_description":"Industrials",
    "feed_risk":46.896,
    "feed_social_activity_percentile":0.409,
    "feed_social_activity_score":4.093,
    "feed_incident_volume_percentile":0.375,
    "feed_incident_volume_score":3.748,
    "feed_actor_threat_percentile":0.494,
    "feed_actor_threat_score":4.941,
    "feed_targeted_asset_percentile":0.582,
    "feed_targeted_asset_score":5.822,
    "feed_effect_impact_percentile":0.509,
    "feed_effect_impact_score":5.095,
    "feed_practice_percentile":0.479,
    "feed_practice_impact_score":4.794
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
feed_risk float The numeric ranking of the total risk or threats that exists in a Feed. It is based on a 1-100 scale, with a higher value representing a higher risk.
feed_social_activity_percentile float The Feeds social activity percentile.
feed_social_activity_score float The amount of social and/or media scrutiny that a particular Feed receives. It is based on a 1-10 scale, with a higher value representing a higher volume.
feed_incident_volume_percentile float The Feeds incident volume percentile.
feed_incident_volume_score float The level of unique reported cyber events that occur within an Feed. It is based on a 1-10 scale, with a higher value representing a higher volume.
feed_actor_threat_percentile float The Feeds actor threat percentile.
feed_actor_threat_score float The threat of the Actors active within a Feed. It is based on a 1-10 scale, with a higher value representing a more impactful set of Actors.
feed_targeted_asset_percentile float The Feeds targeted asset percentile.
feed_targeted_asset_score float The level of risk the impacted Targets experience within a Feed. It is based on a 1-10 scale, with a higher value representing more impactful Targets.
feed_effect_impact_percentile float The Feeds effect impact percentile.
feed_effect_impact_score float The severity of Effects that are results from cyber events that occur within a Feed. It is based on a 1-10 scale, with a higher value representing a more drastic Effect.
feed_practice_percentile float The Feeds practice percentile
feed_practice_impact_score float The level of the Practices typically employed on successful cyber event seen on entities grouped within the Feed. It is based on a 1-10 scale, with a higher value representing more nefarious methods.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Feed Risk Score objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Feed Social Significances Resources

Feed Social Significances

Endpoint

GET https://www.surfwatchlabs.com/api/v3/feedSocialSignificances

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Feed Risk scores

GET https://www.surfwatchlabs.com/api/v3/feedSocialSignificances?startDate=2015-07-27&endDate=2015-07-27
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day": "2015-07-27T00:00:00.000Z",
    "feed_id": -10,
    "feed_description": "Consumer Goods",
    "feed_trend": 21.052631,
    "feed_momentum": 13.652312,
    "feed_significance_score": 25
  },
  {
    "analytic_day": "2015-07-27T00:00:00.000Z",
    "feed_id": -7,
    "feed_description": "Information Technology",
    "feed_trend": 46.491226,
    "feed_momentum": 10.696478,
    "feed_significance_score": 47
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
feed_significance_score integer The social significance score of a Feed. It is based on a 1-100 scale, with a higher value representing a greater level of social 'chatter'.
feed_trend float The trend of the significance score. It is based on a 1-100 scale, with a higher value representing a greater trend.
feed_momentum float The momentum of the significance score. It is based on a 1-100 scale, with a higher value representing greater momentum.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Feed Social Significance objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Headline Resources

Industry Target Headlines

Headlines are typically indicators that something new is occuring, such as a story, event, impacted Industry Target or Practice. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/headlines/industryTargetHeadlines/daily

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
industryId Industry ID to return in the response.

Example Scenarios

Get Industry Target Headlines

GET https://www.surfwatchlabs.com/api/v3/summary/headlines/industryTargetHeadlines/daily?startDate=2015-06-23&endDate=2015-06-23
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day":"2015-06-23T00:00:00.000Z",
    "industry_target_id":204501,
    "industry_target_description":"LOT Polish Airlines",
    "industry_id":-11,
    "industry_description":"Industrials",
    "cyber_facts":[
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":55,
        "cyberfact_type_id": 2,
        "cyberfact_type": "Cyber Attack",
        "cyberfact_source_type_id": 3,
        "cyberfact_source_type": "Social Media",
        "cyberfact_id":284500,
        "event_date":"2015-06-21T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":204501,
            "industry_target_description":"LOT Polish Airlines",
            "industry_id":-11,
            "industry_description":"Industrials",
            "industry_group_id":37,
            "industry_group_description":"Airlines"
          }
        ],
        "tags":[
          {
            "tag_id":101730,
            "tag":"compromised network",
            "macro_tag_id":-509,
            "macro_tag":"Infected/Exploited Assets",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":17597,
            "tag":"unidentified hacker",
            "macro_tag_id":-105,
            "macro_tag":"Identity Unknown",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":204533,
            "tag":"airline ground operations system",
            "macro_tag_id":-247,
            "macro_tag":"Facilities",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          },
          {
            "tag_id":40078,
            "tag":"network security breach",
            "macro_tag_id":-302,
            "macro_tag":"Network Intrusion",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"http://gadgets.ndtv.com/internet/news/hackers-ground-1400-passengers-in-attack-on-polish-airline-lot-706350",
        "cyberfact_type":"Cyber Attack",
        "data_feed_ids":[
          -11,
          -100
        ]
      },
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":69,
        "cyberfact_type_id": 2,
        "cyberfact_type": "Cyber Attack",
        "cyberfact_source_type_id": 3,
        "cyberfact_source_type": "Social Media",
        "cyberfact_id":284462,
        "event_date":"2015-06-21T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":204501,
            "industry_target_description":"LOT Polish Airlines",
            "industry_id":-11,
            "industry_description":"Industrials",
            "industry_group_id":37,
            "industry_group_description":"Airlines"
          }
        ],
        "tags":[
          {
            "tag_id":4313,
            "tag":"service downtime",
            "macro_tag_id":-508,
            "macro_tag":"Service Interruption",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":40078,
            "tag":"network security breach",
            "macro_tag_id":-302,
            "macro_tag":"Network Intrusion",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          },
          {
            "tag_id":17597,
            "tag":"unidentified hacker",
            "macro_tag_id":-105,
            "macro_tag":"Identity Unknown",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":14090,
            "tag":"computer systems",
            "macro_tag_id":-278,
            "macro_tag":"Private Networks",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"http://www.spiegel.de/netzwelt/web/hacker-angriff-auf-polnische-airline-lot-in-warschau-a-1039984.html",
        "cyberfact_type":"Cyber Attack",
        "data_feed_ids":[
          -11,
          -100
        ]
      }
    ]
  },
  {
    "analytic_day":"2015-06-23T00:00:00.000Z",
    "industry_target_id":51853,
    "industry_target_description":"Trustmark Corp.",
    "industry_id":-3,
    "industry_description":"Financials",
    "market":"NASDAQ",
    "cyber_facts":[
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":69,
        "cyberfact_type_id": 8,
        "cyberfact_type": "Data Breach",
        "cyberfact_source_type_id": 2,
        "cyberfact_source_type": "Article",
        "cyberfact_id":284368,
        "event_date":"2015-05-13T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":51853,
            "industry_target_description":"Trustmark Corp.",
            "industry_id":-3,
            "industry_description":"Financials",
            "industry_group_id":85,
            "industry_group_description":"Banks",
            "market":"NASDAQ"
          }
        ],
        "tags":[
          {
            "tag_id":104095,
            "tag":"internal employee",
            "macro_tag_id":-105,
            "macro_tag":"Identity Unknown",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":104335,
            "tag":"client data",
            "macro_tag_id":-211,
            "macro_tag":"Data",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          },
          {
            "tag_id":157454,
            "tag":"design error",
            "macro_tag_id":-308,
            "macro_tag":"Software vulnerability exploit",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          },
          {
            "tag_id":11554,
            "tag":"leaked sensitive data",
            "macro_tag_id":-500,
            "macro_tag":"Data Stolen/Leaked",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"http://oag.ca.gov/ecrime/databreach/reports/sb24-56493",
        "cyberfact_type":"Data Breach",
        "data_feed_ids":[
          -3,
          -100
        ]
      }
    ]
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
cyber_facts array of Cyber Fact objects The Cyber Facts that occured for the analytic day.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry Target Headline objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Practice Tag Headlines

Headlines are typically indicators that something new is occuring, such as a story, event, impacted Industry Target or Practice. View full definition.

A CyberFact is an outline of an information security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/headlines/practiceHeadlines/daily

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Practice Headlines

GET https://www.surfwatchlabs.com/api/v3/summary/headlines/practiceHeadlines/daily?startDate=2015-06-23&endDate=2015-06-23
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day":"2015-06-23T00:00:00.000Z",
    "feed_id":-100,
    "feed_description":"Universal Data Feed",
    "tag_id":204568,
    "tag":"Project Camberdada",
    "macro_tag_id":-309,
    "macro_tag":"Hacking Operation",
    "tag_super_type_id":3,
    "tag_super_type":"Practice",
    "cyber_facts":[
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":81,
        "cyberfact_type_id": 10,
        "cyberfact_type": "Other",
        "cyberfact_source_type_id": 2,
        "cyberfact_source_type": "Article",
        "cyberfact_id":284616,
        "event_date":"2008-01-01T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":101914,
            "industry_target_description":"ESET",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software"
          },
          {
            "industry_target_id":103854,
            "industry_target_description":"AVAST Software",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software",
            "market":"NASDAQ"
          },
          {
            "industry_target_id":134474,
            "industry_target_description":"F-Secure Corporation",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software",
            "market":"OMX"
          },
          {
            "industry_target_id":52597,
            "industry_target_description":"Kaspersky Lab",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software"
          },
          {
            "industry_target_id":105814,
            "industry_target_description":"Softwin",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software"
          }
        ],
        "tags":[
          {
            "tag_id":204568,
            "tag":"Project Camberdada",
            "macro_tag_id":-309,
            "macro_tag":"Hacking Operation",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          },
          {
            "tag_id":103999,
            "tag":"anti-virus software",
            "macro_tag_id":-225,
            "macro_tag":"Security/Utility Software",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          },
          {
            "tag_id":100861,
            "tag":"United Kingdom Government Communications Headquarters",
            "macro_tag_id":-100,
            "macro_tag":"State-sponsored",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":100908,
            "tag":"National Security Agency (NSA)",
            "macro_tag_id":-100,
            "macro_tag":"State-sponsored",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":204610,
            "tag":"subverted security software",
            "macro_tag_id":-526,
            "macro_tag":"Security Bypass",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":204595,
            "tag":"software reverse engineering (SRE)",
            "macro_tag_id":-303,
            "macro_tag":"Unauthorized Access",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"https://newsdesk.moreover.com/click/?p=Q1QyL2E9MjE3MzM0MTcxNDMmcD0xNGUmdj0xJng9RmhMUVlCd0FwaVM5YXJmdWxuTEg5dyZ1MT1ORCZ1Mj1nMzI0OQ&a=21733417143&f=TmV3cw&s=cmljaHhtbA&u=a2V2aW5AaGFja3N1cmZlci5jb20&c=SGFja1N1cmZlcg&ci=105718&i=0&e=VGVjaCBJbnZlc3RvciBOZXdz&d=106985&t=2&k=112935&ck=42f417a6c1bda463e600c1062c670b50",
        "cyberfact_type":"Other",
        "data_feed_ids":[
          -7,
          -100
        ]
      },
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":83,
        "cyberfact_type_id": 2,
        "cyberfact_type": "Cyber Attack",
        "cyberfact_source_type_id": 2,
        "cyberfact_source_type": "Article",
        "cyberfact_id":284493,
        "event_date":"2010-01-01T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":52597,
            "industry_target_description":"Kaspersky Lab",
            "industry_id":-7,
            "industry_description":"Information Technology",
            "industry_group_id":118,
            "industry_group_description":"Software"
          }
        ],
        "tags":[
          {
            "tag_id":11554,
            "tag":"leaked sensitive data",
            "macro_tag_id":-500,
            "macro_tag":"Data Stolen/Leaked",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":204575,
            "tag":"company's emails",
            "macro_tag_id":-211,
            "macro_tag":"Data",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          },
          {
            "tag_id":204576,
            "tag":"monitored emails",
            "macro_tag_id":-523,
            "macro_tag":"Intercepted Communications",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":100861,
            "tag":"United Kingdom Government Communications Headquarters",
            "macro_tag_id":-100,
            "macro_tag":"State-sponsored",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":100908,
            "tag":"National Security Agency (NSA)",
            "macro_tag_id":-100,
            "macro_tag":"State-sponsored",
            "tag_super_type_id":1,
            "tag_super_type":"Actor"
          },
          {
            "tag_id":204568,
            "tag":"Project Camberdada",
            "macro_tag_id":-309,
            "macro_tag":"Hacking Operation",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"https://newsdesk.moreover.com/click/?p=Q1QyL2E9MjE3MzQyMjgwMjkmcD0xNGUmdj0xJng9cWZ6MkZ5S3VXeHpLelhrTEdKVlUyQSZ1MT1ORCZ1Mj1nMzI0OQ&a=21734228029&f=TmV3cw&s=cmljaHhtbA&u=a2V2aW5AaGFja3N1cmZlci5jb20&c=SGFja1N1cmZlcg&ci=105718&i=0&e=RGFpbHlNZS5Db20&d=106985&t=2&k=70976&ck=eab02ef7c5c4ec48e3e80e49894ffb84",
        "cyberfact_type":"Cyber Attack",
        "data_feed_ids":[
          -7,
          -100
        ]
      }
    ]
  },
  {
    "analytic_day":"2015-06-23T00:00:00.000Z",
    "feed_id":-4,
    "feed_description":"Government",
    "tag_id":204608,
    "tag":"Windows PowerShell attack",
    "macro_tag_id":-308,
    "macro_tag":"Software vulnerability exploit",
    "tag_super_type_id":3,
    "tag_super_type":"Practice",
    "cyber_facts":[
      {
        "cyberfact_polarity":-1,
        "cyberfact_score":56,
        "cyberfact_type_id": 2,
        "cyberfact_type": "Cyber Attack",
        "cyberfact_source_type_id": 3,
        "cyberfact_source_type": "Social Media",
        "cyberfact_id":284604,
        "event_date":"2015-06-21T00:00:00.000Z",
        "industry_targets":[
          {
            "industry_target_id":154989,
            "industry_target_description":"United States Office of Personnel Management",
            "industry_id":-4,
            "industry_description":"Government",
            "industry_group_id":139,
            "industry_group_description":"Administration and Support",
            "industry_target_parent_id":52617,
            "industry_target_parent_description":"US government"
          }
        ],
        "tags":[
          {
            "tag_id":204506,
            "tag":"EPIC database",
            "macro_tag_id":-211,
            "macro_tag":"Data",
            "tag_super_type_id":2,
            "tag_super_type":"Target"
          },
          {
            "tag_id":4830,
            "tag":"stolen personal information",
            "macro_tag_id":-522,
            "macro_tag":"Personal Information Stolen/Leaked",
            "tag_super_type_id":5,
            "tag_super_type":"Effect"
          },
          {
            "tag_id":204608,
            "tag":"Windows PowerShell attack",
            "macro_tag_id":-308,
            "macro_tag":"Software vulnerability exploit",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          },
          {
            "tag_id":32684,
            "tag":"remote access Trojan (RAT)",
            "macro_tag_id":-300,
            "macro_tag":"Malware",
            "tag_super_type_id":3,
            "tag_super_type":"Practice"
          }
        ],
        "publication_date":"2015-06-23T00:00:00.000Z",
        "cyberfact_source":"http://itsecuritynews.info/2015/06/22/epic-fail-how-opm-hackers-tapped-the-mother-lode-of-espionage-data/",
        "cyberfact_type":"Cyber Attack",
        "data_feed_ids":[
          -4,
          -100
        ]
      }
    ]
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
tag_id long integer The Practice Cyber Tag the headline is about.
tag string The Practice Cyber Tag the headline is about.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
cyber_facts array of Cyber Fact objects The Cyber Facts that occured for the analytic day.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Practice Tag Headline objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Resources

Industries

Industries represent the industry sectors into which the Industry Targets are categorized. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industries

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Industries

GET https://www.surfwatchlabs.com/api/v3/industries
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "industry_id":-3,
    "industry_description":"Financials"
  },
  {
    "industry_id":-4,
    "industry_description":"Government"
  }
]

Payload Object

Key Value Type Value Description
industry_id integer The unique identifier for the Industry.
industry_description string The description of the Industry.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry by ID

Industries represent the industry sectors into which the Industry Targets are categorized. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industries/{industryId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Industry by ID

GET https://www.surfwatchlabs.com/api/v3/industries/-3
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "industry_id":-3,
  "industry_description":"Financials"
}

Payload Object

Key Value Type Value Description
industry_id integer The unique identifier for the Industry.
industry_description string The description of the Industry.

Response Format

On success, the response status code is 200 OK and the response body contains an Industry object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Groups

IndustryGroups are the sub-groups to Industry sectors and provide a more focused grouping of entities that are involved in the same business activities. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industries/industryGroups

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Industries

GET https://www.surfwatchlabs.com/api/v3/industries/industryGroups
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "industry_group_id":85,
    "industry_group_description":"Banks",
    "industry_id":-3,
    "industry_description":"Financials"
  },
  {
    "industry_group_id":86,
    "industry_group_description":"Consumer Lending",
    "industry_id":-3,
    "industry_description":"Financials"
  }
]

Payload Object

Key Value Type Value Description
industry_group_id integer The unique identifier for the Industry Group.
industry_group_description string The description of the Industry Group.
industry_id integer, Industry ID The Industry the Industry Group belongs to.
industry_description string, Industry The Industry the Industry Group belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry Groups objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Group by ID

IndustryGroups are the sub-groups to Industry sectors and provide a more focused grouping of entities that are involved in the same business activities. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industries/industryGroups/{industryGroupId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Industry by ID

GET https://www.surfwatchlabs.com/api/v3/industries/industryGroups/85
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "industry_group_id":85,
  "industry_group_description":"Banks",
  "industry_id":-3,
  "industry_description":"Financials"
}

Payload Object

Key Value Type Value Description
industry_group_id integer The unique identifier for the Industry Group.
industry_group_description string The description of the Industry Group.
industry_id integer, Industry ID The Industry the Industry Group belongs to.
industry_description string, Industry The Industry the Industry Group belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an Industry Group object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Target Resources

Industry Target Tag by ID

An Industry Target identifies the organizations or individuals affected by a security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industryTargetTags/{industryTargetTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Path parameter Value
industryTargetTagId The ID of the Industry Target to retrieve.

Example Scenarios

Get Industry Target by ID

POST https://www.surfwatchlabs.com/api/v3/industryTargetTags/{industryTargetTagId}
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "industry_target_id": 51475,
  "industry_target_description": "Google Inc.",
  "industry_id": -7,
  "industry_description": "Information Technology",
  "industry_group_id": 117,
  "industry_group_description": "IT Services and Consulting",
  "market": "NASDAQ"
}

Payload Object

Key Value Type Value Description
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry Group that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry Group, which is a subcategory of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains a single Industry Target object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Targets by Cyber Tag ID

Cyber Tags are constructs to describe cyber events. At the highest level of the taxonomy they are categorized into Actor, Target, Effect, Practice and IndustryTarget. View full definition.

An Industry Target identifies the organizations or individuals affected by a security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industryTargetTags/relatedToCyberTag/{cyberTagId}

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Path parameter Value
cyberTagId The ID of the Cyber Tag to find Industry Targets by.

Example Scenarios

Get Industry Targets by Cyber Tag ID

POST https://www.surfwatchlabs.com/api/v3/industryTargetTags/relatedToCyberTag/205373?startDate=2015-06-28&endDate=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "tag_id": 205373,
    "tag": "Fobber trojan",
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "industry_target_id": 205067,
    "industry_target_description": "AdF.ly",
    "industry_id": -7,
    "industry_description": "Information Technology",
    "industry_group_id": 126,
    "industry_group_description": "Internet Services",
    "weight": 2,
    "ranking": 1,
    "first_seen": "2015-06-28T00:00:00.000Z"
  }
]

Payload Object

Key Value Type Value Description
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
weight integer Weight is the confidence that exists between the relationship between the Industry Target and the Cyber Tag in the system.
ranking integer Ranking represents the position on a scale. The lower value represents a higher position on the scale.
first_seen string DateTime the association was first seen.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry Target related to Cyber Tag objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Search Industry Targets

An Industry Target identifies the organizations or individuals affected by a security incident. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industryTargetTags/search

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Search for Industry Targets

GET https://www.surfwatchlabs.com/api/v3/industryTargetTags/search?q=sony
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "industry_target_id": 100403,
    "industry_target_description": "Sony Corp Ord",
    "industry_id": -10,
    "industry_description": "Consumer Goods",
    "industry_group_id": 52,
    "industry_group_description": "Consumer Electronics",
    "market": "NYSE",
    "result_rank": 1,
    "industry_target_synonym": "Sony Corporation"
  },
  {
    "industry_target_id": 159846,
    "industry_target_description": "Sony Online Entertainment LLC",
    "industry_id": -10,
    "industry_description": "Consumer Goods",
    "industry_group_id": 63,
    "industry_group_description": "Entertainment Production",
    "industry_target_parent_id": 100403,
    "industry_target_parent_description": "Sony Corp Ord",
    "market": "NYSE",
    "result_rank": 2,
    "industry_target_synonym": "Sony Online Entertainment LLC"
  },
  {
    "industry_target_id": 170831,
    "industry_target_description": "Sony Mobile Communications AB",
    "industry_id": -7,
    "industry_description": "Information Technology",
    "industry_group_id": 114,
    "industry_group_description": "Communications and Networking",
    "industry_target_parent_id": 100403,
    "industry_target_parent_description": "Sony Corp Ord",
    "market": "NYSE",
    "result_rank": 3,
    "industry_target_synonym": "Sony Mobile Communications AB"
  }
]

Payload Object

Key Value Type Value Description
result_rank integer The search result match ranking.
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
industry_target_synonym string The textual description of the Industry Target Synonym. This value may be different than the Industry Target, for example 'Sony Corporation' is a synonym of 'Sony Corp Ord'.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry Target Search Result objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Industry Target Summary Resources

Industry Target Summaries

Endpoint

GET https://www.surfwatchlabs.com/api/v3/industryTargetSummaries

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
industryId Industry ID to return in the response.
market Market to return in the response.

Example Scenarios

Get Industry Target Summaries

GET https://www.surfwatchlabs.com/api/v3/industryTargetSummaries?startDate=2015-06-23&endDate=2015-06-23
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "industry_target_id": 52597,
    "industry_target_description": "Kaspersky Lab",
    "industry_id": -7,
    "industry_description": "Information Technology",
    "industry_group_id": 118,
    "industry_group_description": "Software",
    "average_cyberfact_score": 69.16666666666667,
    "max_cyberfact_score": 83,
    "std_cyberfact_score": 9.483500493446257,
    "analytic_day": "2015-06-23T00:00:00.000Z"
  },
  {
    "industry_target_id": 103854,
    "industry_target_description": "AVAST Software",
    "industry_id": -7,
    "industry_description": "Information Technology",
    "industry_group_id": 118,
    "industry_group_description": "Software",
    "market": "NASDAQ",
    "average_cyberfact_score": 73.5,
    "max_cyberfact_score": 81,
    "std_cyberfact_score": 10.606601717798213,
    "analytic_day": "2015-06-23T00:00:00.000Z"
  },
  {
    "industry_target_id": 128162,
    "industry_target_description": "Blue Shield of California",
    "industry_id": -3,
    "industry_description": "Financials",
    "industry_group_id": 96,
    "industry_group_description": "Life and Health Insurance",
    "average_cyberfact_score": 69,
    "max_cyberfact_score": 69,
    "std_cyberfact_score": 0,
    "analytic_day": "2015-06-23T00:00:00.000Z"
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
average_cyberfact_score float The average Cyber Fact score for the Industry Target for the analytic_day.
std_cyberfact_score float The statistical standard deviation of the Cyber Fact score for the Industry Target for the analytic_day.
max_cyberfact_score float The statistical maximum of the Cyber Fact score for the Industry Target for the analytic_day.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Industry Target Summary objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Macro Percentages Resources

Daily Macro Percentages

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/daily

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Daily Macro Percentages

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/daily?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 1,
    "macro_percentage": 30.76923
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -308,
    "macro_tag": "Software vulnerability exploit",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 1,
    "macro_percentage": 30.76923
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -304,
    "macro_tag": "Social Engineering",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 3,
    "macro_percentage": 15.384615
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
macro_ranking float The ranking of the Macro Tag within the Feed and Tag Super Type within the analytic time range.
macro_percentage float The percentage occurance of the Macro Tag within the Feed and Tag Super Type within the analytic time range.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Macro Percentage objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Weekly Macro Percentages

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/weekly

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Daily Weekly Percentages

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/weekly?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 1,
    "macro_percentage": 29.62963
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 2,
    "macro_percentage": 25.925926
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -308,
    "macro_tag": "Software vulnerability exploit",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 3,
    "macro_percentage": 22.222221
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
macro_ranking float The ranking of the Macro Tag within the Feed and Tag Super Type within the analytic time range.
macro_percentage float The percentage occurance of the Macro Tag within the Feed and Tag Super Type within the analytic time range.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Macro Percentage objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Monthly Macro Percentages

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/monthly

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Monthly Macro Percentages

GET https://www.surfwatchlabs.com/api/v3/summary/macroPercentages/monthly?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 1,
    "macro_percentage": 29.824562
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -303,
    "macro_tag": "Unauthorized Access",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 2,
    "macro_percentage": 19.298246
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -302,
    "macro_tag": "Network Intrusion",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 3,
    "macro_percentage": 13.157895
  },
  {
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "macro_tag_id": -304,
    "macro_tag": "Social Engineering",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "macro_ranking": 3,
    "macro_percentage": 13.157895
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
macro_ranking float The ranking of the Macro Tag within the Feed and Tag Super Type within the analytic time range.
macro_percentage float The percentage occurance of the Macro Tag within the Feed and Tag Super Type within the analytic time range.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Macro Percentage objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Macro Trend Resources

Monthly Macro Trend Deltas

Macro Trend Delta is a 30 day trend (index of proportionality) score for Macro Tags, and the calculated delta (change) in score on a daily basis. This value will then be compared to the mean and standard deviation of the delta over the last 120 days of computed data. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/macroTrendDelta/monthly

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
tagSuperTypeId Super Type ID to return in the response.

Example Scenarios

Get Monthly Macro Trend Deltas from 2015-06-26 to 2015-06-28

GET https://www.surfwatchlabs.com/api/v3/summary/macroTrendDelta/monthlystartDate=2015-06-25&endDate=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "trend_delta_mean": 45.65458,
    "trend_delta_standard_dev": 40.909,
    "trend_delta_max": 217.21136,
    "trend_delta_min": 0.0031080402,
    "trend_delta_threshold": 1.2747258,
    "deltas": [
      {
        "analytic_day": "2015-06-26T00:00:00.000Z",
        "macro_trend": 664.52734,
        "macro_trend_delta": -10.539376
      },
      {
        "analytic_day": "2015-06-27T00:00:00.000Z",
        "macro_trend": 661.3973,
        "macro_trend_delta": -3.1300507
      },
      {
        "analytic_day": "2015-06-28T00:00:00.000Z",
        "macro_trend": 679.5709,
        "macro_trend_delta": 18.173603
      }
    ]
  },
  {
    "macro_tag_id": -301,
    "macro_tag": "Network Attack",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "trend_delta_mean": 20.585863,
    "trend_delta_standard_dev": 25.940432,
    "trend_delta_max": 185.91776,
    "trend_delta_min": 0.05574111,
    "trend_delta_threshold": 0.72466725,
    "deltas": [
      {
        "analytic_day": "2015-06-26T00:00:00.000Z",
        "macro_trend": 140.3931,
        "macro_trend_delta": -0.4827798
      },
      {
        "analytic_day": "2015-06-27T00:00:00.000Z",
        "macro_trend": 144.45354,
        "macro_trend_delta": 4.060429
      },
      {
        "analytic_day": "2015-06-28T00:00:00.000Z",
        "macro_trend": 147.85448,
        "macro_trend_delta": 3.400948
      }
    ]
  }
]

Payload Object

Key Value Type Value Description
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
trend_delta_mean float The statistical mean of the trend delta across the last 120 days.
trend_delta_standard_dev float The statistical standard deviation of the trend delta across the last 120 days.
trend_delta_max float The statistical maximum of the trend delta across the last 120 days.
trend_delta_min float The statistical minimum of the trend delta across the last 120 days.
trend_delta_threshold float The statistical threshold of the trend delta across the last 120 days.
deltas array of Macro Trend Delta objects Array of trend delta objects for each analytic_day for given time range.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Macro Delta objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Market Resources

Markets

Markets represent the list of Market acronyms that are used in the system. Publicly traded Industry Targets have their Markets listed as a possible filter or query mechanism. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/markets

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Markets

GET https://www.surfwatchlabs.com/api/v3/markets
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "market": "LSE",
    "market_description": "London Stock Exchange"
  },
  {
    "market": "NYSE",
    "market_description": "New York Stock Exchange"
  },
  {
    "market": "TYO",
    "market_description": "Tokyo Stock Exchange"
  }
]

Payload Object

Key Value Type Value Description
market string The common abbreviation for the Market.
market_description string The description of the Market.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Market objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Phishing Resources

Daily Industry Target Phishing Summaries

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/phishing/industryTargets/daily

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
industryId Industry ID to return in the response.

Example Scenarios

Get Phishing Industry Target summaries

GET https://www.surfwatchlabs.com/api/v3/summary/phishing/industryTargets/daily?startDate=2016-01-20&endDate=2016-01-20
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "industry_target_id":50200,
    "industry_target_description":"Apple Inc.",
    "industry_id":-7,
    "industry_description":"Information Technology",
    "industry_group_id":115,
    "industry_group_description":"Computer Hardware",
    "market":"NASDAQ",
    "analytic_day":"2016-01-24T00:00:00.000Z",
    "phishing_total_count":938,
    "phishing_industry_target_count":116,
    "phishing_industry_target_percentage":12.366737
  },
  {
    "industry_target_id":50234,
    "industry_target_description":"Yahoo! Inc.",
    "industry_id":-7,
    "industry_description":"Information Technology",
    "industry_group_id":117,
    "industry_group_description":"IT Services and Consulting",
    "market":"NASDAQ",
    "analytic_day":"2016-01-24T00:00:00.000Z",
    "phishing_total_count":938,
    "phishing_industry_target_count":13,
    "phishing_industry_target_percentage":1.3859276
  },
  {
    "industry_target_id":50564,
    "industry_target_description":"Amazon.com, Inc.",
    "industry_id":-10,
    "industry_description":"Consumer Goods",
    "industry_group_id":71,
    "industry_group_description":"Other Specialty Retailers",
    "market":"NASDAQ",
    "analytic_day":"2016-01-24T00:00:00.000Z",
    "phishing_total_count":938,
    "phishing_industry_target_count":16,
    "phishing_industry_target_percentage":1.7057569
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
phishing_total_count long integer The total count of phishing events for the analytic day.
phishing_industry_target_count long integer The total count of phishing events for the Industry Target for the analytic day.
phishing_industry_target_percentage float The percentage of phishing events for the Industry Target for the analytic day.
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry Group that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry Group, which is a subcategory of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Phishing Industry Target objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted CyberFact Resources

Submitting CyberFacts

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

POST https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts

Request Headers

Header parameter Value Required
X-SHARED-TO A single or comma-deleted value of Cyber Data Group IDs to share the CyberFact(s) to. Yes
X-SUBMITTING-LICENSE-ID The Cyber Risk Cloud license ID used for submitting the CyberFact. Yes
X-TO-SANITIZE Boolean to determine whether CyberFact(s) is to be sanitized; defaults to true. Marking a CyberFact as sanitized means they are to be sanitized before being saved in the SurfWatch Labs Data Warehouse. An unmolested copy of the CyberFact is stored in the SurfWatch Labs Submitted Data Store. Sanitization removes sensitive information from SurfWatch Labs analytics. By not sanitizing a CyberFact, SurfWatch Labs will use all data fields in the CyberFact for analytical purposes. No
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Content-Type Only application/json is accepted. Yes

Response Headers

Header parameter Value
Location The URI to the submitted CyberFact that was created.

Example Scenarios

Submit CyberFact to single Cyber Data Group

POST https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json
X-TO-SANITIZE: true
X-SUBMITTING-LICENSE-ID: {submitting-license-id}
X-SHARED-TO: {cdg-id-1}

Submit CyberFact to multiple Cyber Data Groups

POST https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json
X-TO-SANITIZE: true
X-SUBMITTING-LICENSE-ID: {submitting-license-id}
X-SHARED-TO: {cdg-id-1},{cdg-id-2},{cdg-id-3}

Example Payload

{
  "cyberfact_polarity":-1,
  "event_date":"2014-11-05T06:00:00.000Z",
  "industry_targets":[
    {
      "industry_target_id":-1000,
      "industry_target_description":"SurfWatch Labs",
      "industry_id":-7,
      "industry_description":"Information Technology"
    }
  ],
  "tags":[
    {
      "tag":".htaccess basic authorization attempts",
      "tag_id":-1004,
      "macro_tag_id":-303,
      "macro_tag":"Unauthorized Access",
      "tag_super_type_id":3,
      "tag_super_type":"Practice"
    },
    {
      "tag":"SurfWatch Labs API server",
      "tag_id":-1001,
      "macro_tag_id":-240,
      "macro_tag":"Network Resources",
      "tag_super_type_id":2,
      "tag_super_type":"Target"
    },
    {
      "tag":"112.90.55.152",
      "tag_id":-1003,
      "macro_tag_id":-105,
      "macro_tag":"Identity Unknown",
      "tag_super_type_id":1,
      "tag_super_type":"Actor"
    },
    {
      "tag":"unidentified Chinese hacker",
      "tag_id":-1002,
      "macro_tag_id":-105,
      "macro_tag":"Identity Unknown",
      "tag_super_type_id":1,
      "tag_super_type":"Actor"
    }
  ]
}

Payload Object

To be considered valid and submittable, the CyberFact payload must contain:

  • An Event Date
  • At least one complete Industry Target object containing:
    • industry_target_description
    • industry_description
  • At least one complete Cyber Tag object containing:
    • tag
    • macro_tag
    • tag_super_type

Key Value Type Value Description
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 201 Created, there will be a Location response header, and the response body will be empty.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted CyberFact by ID

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cyberFactId}

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Response Headers

Header parameter Value
Content-Type Only application/json is returned.

Request Parameters

Path parameter Value
cyberFactId The ID of the Submitted CyberFact to retrieve. Requesting user must have access to CyberFact via one or more Cyber Data Groups.
enrichCyberFacts A boolean value used to indicate whether to enrich the CyberFact in the response. Defaults to false. Current enrichment includes computation of computed_tag_id for Submitted Cyber Tag, computed_industry_target_id for Submitted Industry Target objects.

Example Scenarios

Get CyberFact by ID

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/-2
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "cyberfact_id":-2,
  "cyberfact_polarity":-1,
  "publication_date":"2014-11-14T06:00:00.000Z",
  "event_date":"2014-11-05T06:00:00.000Z",
  "sanitized":false,
  "cyberfact_type_id":2,
  "cyberfact_score":0,
  "industry_targets":[
    {
      "industry_target_id":-1000,
      "industry_target_description":"SurfWatch Labs",
      "industry_id":-7,
      "industry_description":"Information Technology"
    }
  ],
  "tags":[
    {
      "tag":".htaccess basic authorization attempts",
      "tag_id":-1004,
      "macro_tag_id":-303,
      "macro_tag":"Unauthorized Access",
      "tag_super_type_id":3,
      "tag_super_type":"Practice"
    },
    {
      "tag":"SurfWatch Labs API server",
      "tag_id":-1001,
      "macro_tag_id":-240,
      "macro_tag":"Network Resources",
      "tag_super_type_id":2,
      "tag_super_type":"Target"
    },
    {
      "tag":"112.90.55.152",
      "tag_id":-1003,
      "macro_tag_id":-105,
      "macro_tag":"Identity Unknown",
      "tag_super_type_id":1,
      "tag_super_type":"Actor"
    },
    {
      "tag":"unidentified Chinese hacker",
      "tag_id":-1002,
      "macro_tag_id":-105,
      "macro_tag":"Identity Unknown",
      "tag_super_type_id":1,
      "tag_super_type":"Actor"
    }
  ],
  "submitting_user_id":"usr1234567890",
  "submitting_organization_id":"org1234567890",
  "cyber_data_group_ids":[
    "cdg1234567890"
  ]
 }

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for Submitted CyberFact.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
publication_date Date Time The date the CyberFact was submitted to the SurfWatch Labs Submitted Data Store. Date parameters must be formatted according to Joda's ISODateTimeFormat
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
sanitized boolean Marking a CyberFact as sanitized means they are to be sanitized before being saved in the SurfWatch Labs Data Warehouse. An unmolested copy of the CyberFact is stored in the SurfWatch Labs Submitted Data Store. Sanitization removes sensitive information from SurfWatch Labs analytics. By not sanitizing a CyberFact, SurfWatch Labs will use all data fields in the CyberFact for analytical purposes.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
cyber_data_group_ids array of Cyber Data Group Ids The Cyber Data Group Id(s) that have access to the CyberFact.
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
tags array of Submitted Cyber Tag objects The Submitted Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains a single Submitted CyberFact (GET) object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Get Submitted CyberFacts

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Request Parameters

Query parameter Value
cfId One or more CyberFact IDs to retrieve. When set all other query parameters will be ignored.
allReadableCfs A boolean value that when set to true will return all readable CyberFacts for a user. When set any individual Cyber Data Group IDs query parameters will be ignored.
cdgId Conditionally Required. One or more Cyber Data Group IDs to retrieve. Value is required when not retrieving an explicit set of CyberFact IDs (one or more cfId query params) or when allReadableCfs=true is set.
cdgIds[] Conditionally Required. One or more Cyber Data Group IDs to retrieve. When used will cause cdgId query parameters to be ignored. Value is required when not retrieving an explicit set of CyberFact IDs (one or more cfId query params) or when allReadableCfs=true is set.
startDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is required when not retrieving an explicit set of CyberFact IDs, or when using the yesterday=true query option. Maximum: 90 day date range.
endDate Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the end date time of the query. Value is required when not retrieving an explicit set of IDs, or when using the yesterday=true query option. Maximum: 90 day date range.
yesterday A boolean value used to set the date range of a query to yesterday. When set the startDate and endDate query parameters will be ignored.
limitResultSet An optional boolean value used to limit the number of CyberFacts returned by the request. When used numResults is required and beforeCyberFactId and offset are optional.
numResults Conditionally Required. This is used with limitResultSet to limit the number of CyberFacts returned by the request.
beforeCyberFactId An optional CyberFact Id used to return results that are only older than the provided Id. This can be used for queries where the X-MORE-RESULTS header is set to true, allowing pagination to retrieve more CyberFacts.
offset An optional 0-based index value used to to return values after that index value of the result set. This can be used for queries where the X-MORE-RESULTS header is set to true, allowing pagination to retrieve more CyberFacts.
industryId An optional integer value used to filter the results by an Industry ID.
enrichCyberFacts A boolean value used to indicate whether to enrich the CyberFact in the response. Defaults to false. Current enrichment includes computation of computed_tag_id for Submitted Cyber Tag, computed_industry_target_id for Submitted Industry Target objects.

Response Headers

Header parameter Value
X-CYBERFACTS-NOT-FOUND 1-n CyberFact Ids that were not found by the request. This header is only applicable to responses where cfId was part of the request, and then only if the cdIf was not found.
X-MORE-RESULTS A boolean value to indicate whether more results could be retrieved by the query. This value is not present for queries for specific CyberFact Ids. Currently a maximum of 100 CyberFacts are returned for a given query.
X-TOTAL-RESULTS A numeric value to indicate the total number of results could be retrieved by the query. When the header X-MORE-RESULTS=true this value will reflect the total number of results retrievable even though the maximum number was returned. To get more results in this situation, either issue the same query with the beforeCyberFactId query param set to the oldest (last) result returned, issue the same query with the offset query param set, or use both beforeCyberFactId and offset query params together (beforeCyberFactId applied first).

Example Scenarios

Get all readable CyberFacts for a user

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?allReadableCfs=true&startDate=2015-01-01&endDate=2015-01-07
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Get additional readable CyberFacts for a user with beforeCyberFactId query param

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?allReadableCfs=true&beforeCyberFactId={cf-id-123}&startDate=2015-01-01&endDate=2015-01-07
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Get additional readable CyberFacts for a user with offset query param

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?allReadableCfs=true&offset=100&startDate=2015-01-01&endDate=2015-01-07
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Get additional readable CyberFacts for a user with beforeCyberFactId and offset query params

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?allReadableCfs=true&beforeCyberFactId={cf-id-123}&offset=100&startDate=2015-01-01&endDate=2015-01-07
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Get multiple CyberFacts by ID

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?cfId={cf-id-1}&cfId={cf-id-2}&cfId={cf-id-3}
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Get multiple CyberFacts by Cyber Data Group IDs

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts?cdgId={cdg-id-1}&cdgId={cdg-id-2}&cdgId={cdg-id-3}&startDate=2015-01-01&endDate=2015-01-07
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Example Payload

[
  {
    "cyberfact_id":-2,
    "cyberfact_polarity":-1,
    "publication_date":"2014-11-14T06:00:00.000Z",
    "event_date":"2014-11-05T06:00:00.000Z",
    "sanitized":false,
    "cyberfact_type_id":2,
    "cyberfact_score":0,
    "industry_targets":[
      {
        "industry_target_id":-1000,
        "industry_target_description":"SurfWatch Labs",
        "industry_id":-7,
        "industry_description":"Information Technology"
      }
    ],
    "tags":[
      {
        "tag":".htaccess basic authorization attempts",
        "tag_id":-1004,
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
      {
        "tag":"SurfWatch Labs API server",
        "tag_id":-1001,
        "macro_tag_id":-240,
        "macro_tag":"Network Resources",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag":"112.90.55.152",
        "tag_id":-1003,
        "macro_tag_id":-105,
        "macro_tag":"Identity Unknown",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      },
      {
        "tag":"unidentified Chinese hacker",
        "tag_id":-1002,
        "macro_tag_id":-105,
        "macro_tag":"Identity Unknown",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      }
    ],
    "submitting_user_id":"usr1234567890",
    "submitting_organization_id":"org1234567890",
    "cyber_data_group_ids":[
      "cdg1234567890"
    ]
   },
   {
    "cyberfact_id":-4,
    "cyberfact_polarity":-1,
    "publication_date":"2014-11-19T06:00:00.000Z",
    "event_date":"2014-11-15T06:00:00.000Z",
    "sanitized":false,
    "cyberfact_type_id":2,
    "cyberfact_score":0,
    "industry_targets":[
    {
      "industry_target_id":-1009,
      "industry_target_description":"SurfWatch Labs",
      "industry_id":-7,
      "industry_description":"Information Technology"
    }
    ],
    "tags":[
      {
        "tag":"Apache Struts",
        "tag_id":-1007,
        "macro_tag_id":-284,
        "macro_tag":"Cloud Services/Applications",
        "tag_super_type_id":2,
        "tag_super_type":"Target"
      },
      {
        "tag":"allows unauthorized access",
        "tag_id":-1010,
        "macro_tag_id":-509,
        "macro_tag":"Infected/Exploited Assets",
        "tag_super_type_id":5,
        "tag_super_type":"Effect"
      },
      {
        "tag":"unsuccessful attempt",
        "tag_id":-1006,
        "macro_tag_id":-303,
        "macro_tag":"Unauthorized Access",
        "tag_super_type_id":3,
        "tag_super_type":"Practice"
      },
        {
        "tag":"222.143.28.101",
        "tag_id":-1011,
        "macro_tag_id":-105,
        "macro_tag":"Identity Unknown",
        "tag_super_type_id":1,
        "tag_super_type":"Actor"
      }
    ],
    "submitting_user_id":"usr1234567890",
    "submitting_organization_id":"org1234567890",
    "cyber_data_group_ids":[
      "cdg1234567890"
    ]
  }
]

Payload Object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for Submitted CyberFact.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
publication_date Date Time The date the CyberFact was submitted to the SurfWatch Labs Submitted Data Store. Date parameters must be formatted according to Joda's ISODateTimeFormat
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
sanitized boolean Marking a CyberFact as sanitized means they are to be sanitized before being saved in the SurfWatch Labs Data Warehouse. An unmolested copy of the CyberFact is stored in the SurfWatch Labs Submitted Data Store. Sanitization removes sensitive information from SurfWatch Labs analytics. By not sanitizing a CyberFact, SurfWatch Labs will use all data fields in the CyberFact for analytical purposes.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
cyber_data_group_ids array of Cyber Data Group Ids The Cyber Data Group Id(s) that have access to the CyberFact.
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
tags array of Submitted Cyber Tag objects The Submitted Cyber Tags that describe the CyberFact.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Submitted CyberFact (GET) objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

CyberFacts Sharing Permissions

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

PUT https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/sharedTo

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Response Headers

Header parameter Value
Content-Type Only application/json is returned.

Request Parameters

Query parameter Value
dropExistingShareTo Boolean value used to drop all permissions for provided CyberFacts. Must provide cyber_data_group_ids_to_include in payload when using this operation. Defaults to false.

Example Scenarios

Share CyberFact(s) to additional Cyber Data Groups

PUT https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/sharedTo
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

{
  "cyberfact_ids": [
    {cf-id-1},
    {cf-id-2}
  ],
  "cyber_data_group_ids_to_include": [
    "{cdg-id-1}",
    "{cdg-id-2}"
  ]
}

Revoke sharing CyberFact(s) to Cyber Data Groups

PUT https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/sharedTo
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

{
  "cyberfact_ids": [
    {cf-id-1},
    {cf-id-2}
  ],
  "cyber_data_group_ids_to_exclude": [
    "{cdg-id-1}",
    "{cdg-id-2}"
  ]
}

Reset sharing permissions on CyberFact(s), and share to new Cyber Datat Groups

PUT https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/sharedTo?dropExistingShareTo=true
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

{
  "cyberfact_ids": [
    {cf-id-1},
    {cf-id-2}
  ],
  "cyber_data_group_ids_to_include": [
    "{cdg-id-1}",
    "{cdg-id-2}"
  ]
}

Example Payload

{
  "cyberfact_ids": [
    {cf-id-1},
    {cf-id-2}
  ],
  "cyber_data_group_ids_to_include": [
    "{cdg-id-1}",
    "{cdg-id-2}"
  ],
  "cyber_data_group_ids_to_exclude": [
    "{cdg-id-3}",
    "{cdg-id-4}"
  ]
}

Payload Object

Key Value Type Value Description
cyberfact_ids array of CyberFact Ids The CyberFact Id(s) for this operation to modify.
cyber_data_group_ids_to_include array of Cyber Data Group Ids The Cyber Data Group Id(s) to add to the provided CyberFacts.
cyber_data_group_ids_to_exclude array of Cyber Data Group Ids The Cyber Data Group Id(s) to remove from the provided CyberFacts.

Response Format

On success, the response status code is 200 OK and the response body will be empty.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted Note Resources

Submitting CyberFact Notes

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

Submitted CyberFact Notes are additional data associated with a Submitted CyberFact. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

POST https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cyberFactId}/notes

Request Headers

Header parameter Value Required
X-SUBMITTING-LICENSE-ID The Cyber Risk Cloud license ID used for submitting the CyberFact. Yes
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Content-Type Only application/json is accepted. Yes

Request Parameters

Path parameter Value
cyberFactId The id of the CyberFact which the notes are attached to. Requesting user must have access to CyberFact via one or more Cyber Data Groups.

Response Headers

Header parameter Value
Location The URI to the submitted CyberFact that was created.

Example Scenarios

Submit CyberFact Note for {cf-id-1}

POST https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cf-id-1}/notes
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json
X-SUBMITTING-LICENSE-ID: {submitting-license-id}

Example Payload

{
  "note_value": "This CyberFact represents the first time the Citadel malware was identified on our internal infrastructure.",
  "note_type_id": 4
}

Payload Object

To be considered valid and submittable, the CyberFact Note payload must contain:

  • A Note Value
  • A Note Type Id

Key Value Type Value Description
note_value string The content of the note.
note_type_id integer, Submitted Note Type Id The unique identifier for the note type.
note_parent_id integer, Submitted Note Type Id The unique identifier for the note that is the parent to this note.

Response Format

On success, the response status code is 201 Created, there will be a Location response header, and the response body will be empty.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted CyberFact Note by ID

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

Submitted CyberFact Notes are additional data associated with a Submitted CyberFact. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cyberFactId}/notes/{cyberFactNoteId}

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Response Headers

Header parameter Value
Content-Type Only application/json is returned.

Request Parameters

Path parameter Value
cyberFactId The ID of the CyberFact which the notes are attached to. Requesting user must have access to CyberFact via one or more Cyber Data Groups.
cyberFactNoteId The ID of the Submitted CyberFact Note to retrieve. Requesting user must have access to CyberFact via one or more Cyber Data Groups.

Example Scenarios

Get Submitted CyberFact Note by ID

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cf-id-1}/notes/1
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Example Payload

{
  "node_id":1,
  "note_value": "This CyberFact represents the first time the Citadel malware was identified on our internal infrastructure.",
  "note_type_id": 4
  "note_type":"note",
  "submitting_user_id":"usr1234567890",
  "submitting_organization_id":"org1234567890"
}

Payload Object

Key Value Type Value Description
note_id long integer The unique identifier for the note.
note_value string The content of the note.
cyberfact_id long integer, Submitted CyberFact Id The unique identifier for the Submitted CyberFact that the note pertains to.
note_type_id integer, Submitted Note Type Id The unique identifier for the note type.
note_type String, Submitted Note Type The short textual description of the note type.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
note_parent_id integer, Submitted Note Type Id The unique identifier for the note that is the parent to this note. The note_parent_id is used for note structures like comment chains.

Response Format

On success, the response status code is 200 OK and the response body contains a single Submitted CyberFact Note object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted CyberFact Notes

A CyberFact that has been submitted to the Cyber Risk Cloud. View full definition.

Submitted CyberFact Notes are additional data associated with a Submitted CyberFact. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cyberFactId}/notes

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Response Headers

Header parameter Value
Content-Type Only application/json is returned.

Request Parameters

Path parameter Value
cyberFactId The ID of the CyberFact which the notes are attached to. Requesting user must have access to CyberFact via one or more Cyber Data Groups.

Example Scenarios

Get all notes for a CyberFact

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberFacts/{cf-id-1}/notes
app-id: {your-app-id}
app-key: {your-app-key}
Content-Type: application/json

Example Payload

[
  {
    "node_id":1,
    "note_value": "This CyberFact represents the first time the Citadel malware was identified on our internal infrastructure.",
    "note_type_id": 4
    "note_type":"note",
    "submitting_user_id":"usr1234567890",
    "submitting_organization_id":"org1234567890"
  },
  {
    "note_id":2,
    "note_type_id":3,
    "note_type":"comment",
    "note_value":"This is concerning.. we're our IDS systems able to detect this?",
    "submitting_user_id":"usr0987654321",
    "submitting_organization_id":"org1234567890"
  },
  {
    "note_id":3,
    "note_type_id":3,
    "note_type":"comment",
    "note_value":"No, unfortunately we did not detect this infection.",
    "note_parent_id":2
    "submitting_user_id":"usr1234567890",
    "submitting_organization_id":"org1234567890",
  }
]

Payload Object

Key Value Type Value Description
note_id long integer The unique identifier for the note.
note_value string The content of the note.
cyberfact_id long integer, Submitted CyberFact Id The unique identifier for the Submitted CyberFact that the note pertains to.
note_type_id integer, Submitted Note Type Id The unique identifier for the note type.
note_type String, Submitted Note Type The short textual description of the note type.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
note_parent_id integer, Submitted Note Type Id The unique identifier for the note that is the parent to this note. The note_parent_id is used for note structures like comment chains.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Submitted CyberFact Note objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted Lookup Resources

Cyber Data Groups

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberDataGroups

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Cyber Data Groups

GET https://www.surfwatchlabs.com/api/v3/submitted/cyberDataGroups
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "id": "54bec831726f676f9b430000",
    "name": "SurfWatch Labs CyberData",
    "discoverable": false,
    "description": "General CyberFacts for SurfWatch Labs cyber activity."
  },
  {
    "id": "54bec832726f676f9b470000",
    "name": "SurfWatch Labs DDoS activity",
    "discoverable": false,
    "description": "CyberFacts generated from RackSpace DDoS prevention."
  }
]

Payload Object

Key Value Type Value Description
id string The unique identifier for the Cyber Data Group.
name string The name of the Cyber Data Group.
discoverable boolean When true, the Cyber Data Group is able to be discovered by other Cyber Risk Cloud users. Those users may then request to join the Cyber Data Group, and the Cyber Data Group admin(s) may then choose to allow or reject that request.
description string A description of the Cyber Data Group.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Cyber Data Group objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Submitted Note Types

Submitted Notes Types are the available types accepted in the Cyber Risk Cloud. View full definition.

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/notes/types

Request Headers

Header parameter Value Required
app_id SurfWatch Labs Application ID. See My API Profile for details. Yes
app_key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Only application/json is provided. No

Response Headers

Header parameter Value
Content-Type Only application/json is returned.

Example Scenarios

Get Submitted Note Types

GET https://www.surfwatchlabs.com/api/v3/submitted/notes/types
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "note_type_id": 1,
    "note_type": "url",
    "note_description": "Default note that allows placement of a url"
  },
  {
    "note_type_id": 3,
    "note_type": "comment",
    "note_description": "Default note that allows user to submit comments against CyberFacts and other comments"
  },
  {
    "note_type_id": 4,
    "note_type": "note",
    "note_description": "Default note that allows users to submit supporting data related to the CyberFact"
  }
]

Payload Object

Key Value Type Value Description
note_type_id short integer The unique identifier for the note type.
note_type string The short textual description of the note type.
note_description string The textual description of the note type.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Submitted Note Type objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Cyber Risk Cloud License Information

With SurfWatch Cyber Risk Cloud, you can safely submit and store your evaluated cyber event data in a private cloud for analysis, visualization and understanding across your organization. When combined with SurfWatch C-Suite you can compare your cyber data to a broader set of cyber intelligence for enriched risk management analysis and insights. View full definition.

Endpoint

GET https://www.surfwatchlabs.com/api/v3/submitted/licenseInformation

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Example Scenarios

Get Cyber Risk Cloud License Information

GET https://www.surfwatchlabs.com/api/v3/submitted/licenseInformation
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

{
  "id": "54ff2537726f6774470a0000",
  "description": "Cyber Risk Cloud license for a happy company.",
  "license_users": [
    {
      "id": "5413a94d726f676b2a010000",
      "email": "user1@company.com"
    },
    {
      "id": "54614d53726f670de8000000",
      "email": "user2@company.com"
    },
    {
      "id": "54b98c65726f6717ee010000",
      "email": "user3@company.com"
    }
  ]
}

Payload Object

Key Value Type Value Description
id string The unique identifier for the Cyber Risk Cloud license.
description string A description of the Cyber Risk Cloud license.
license_users array An array of all of the users who occupy a seat for the license.
license_users.id string The unique identifier for the Cyber Risk Cloud user.
license_users.email string The email of the Cyber Risk Cloud user.

Response Format

On success, the response status code is 200 OK and the response body contains a Cyber Risk Cloud License Information object in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Tag Trend Resources

Daily Tag Trend

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/daily

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Daily Tag Trends

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/daily?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_interval": "2015-06-27T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 16237,
    "tag": "human error",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 16,
    "tag_trend_rank": 1,
    "tag_momentum": 1
  },
  {
    "analytic_interval": "2015-06-27T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 101986,
    "tag": "employee negligence",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 16,
    "tag_trend_rank": 2,
    "tag_momentum": 1
  },
  {
    "analytic_interval": "2015-06-27T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 4059,
    "tag": "spam",
    "macro_tag_id": -304,
    "macro_tag": "Social Engineering",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 8,
    "tag_trend_rank": 3,
    "tag_momentum": 1
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
analytic_day Interval The datetime interval over which the analytic was run.
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_trend float The percentage of activity of a Cyber Tag within a Macro Tag category for a particular Feed.
tag_trend_rank float Indicates the rank of a Cyber Tag's activity within a Macro Tag category for a particular Feed.
tag_momentum float Indicates decreased, unchanged, or increased (-1, 0, 1) Cyber Tag activity within a Macro Tag category for a particular Feed.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Tag Trend objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Weekly Tag Trend

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/weekly

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Weekly Tag Trends

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/weekly?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_interval": "2015-06-21T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 101986,
    "tag": "employee negligence",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 15,
    "tag_trend_rank": 1,
    "tag_momentum": 1
  },
  {
    "analytic_interval": "2015-06-21T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 16237,
    "tag": "human error",
    "macro_tag_id": -306,
    "macro_tag": "Insider Activity",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 12,
    "tag_trend_rank": 2,
    "tag_momentum": 1
  },
  {
    "analytic_interval": "2015-06-21T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 40078,
    "tag": "network security breach",
    "macro_tag_id": -302,
    "macro_tag": "Network Intrusion",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 12,
    "tag_trend_rank": 3,
    "tag_momentum": -1
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
analytic_day Interval The datetime interval over which the analytic was run.
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_trend float The percentage of activity of a Cyber Tag within a Macro Tag category for a particular Feed.
tag_trend_rank float Indicates the rank of a Cyber Tag's activity within a Macro Tag category for a particular Feed.
tag_momentum float Indicates decreased, unchanged, or increased (-1, 0, 1) Cyber Tag activity within a Macro Tag category for a particular Feed.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Tag Trend objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.

Monthly Tag Trend

Endpoint

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/monthly

Request Headers

Header parameter Value Required
app-id SurfWatch Labs Application ID. See My API Profile for details. Yes
app-key SurfWatch Labs Application Key. See My API Profile for details. Yes
Accept Media types application/json and text/csv are provided. To work around some libraries handling of non-standard-ish media types, text/plain can be used in lieu of text/csv. Defaults to application/json. No

Response Headers

Header parameter Value
Content-Type Media type application/json, text/csv or text/plain is returned.

Request Parameters

Query parameter Value
date Conditionally Required. A properly formatted date or datetime, using Joda's ISODateTimeFormat, to indicate the start date time of the query. Value is not required when using the yesterday=true query option.
yesterday A boolean value used to set the date range of a query to yesterday. When set the date query parameter will be ignored.
tagSuperTypeId Super Type ID to return in the response.
feedId One or more Feed IDs to return in the response.
feedIds[] One or more Feed IDs to return in the response. When used will cause feedId query parameters to be ignored.
excludeFeedId One or more Feed IDs to filter from the response.
excludeFeedIds[] One or more Feed IDs to return in the response. When used will cause excludeFeedId query parameters to be ignored.

Example Scenarios

Get Monthly Tag Trends

GET https://www.surfwatchlabs.com/api/v3/summary/tagTrend/monthly?date=2015-06-28
app-id: {your-app-id}
app-key: {your-app-key}
Accept: application/json

Example Payload

[
  {
    "analytic_interval": "2015-05-29T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 40078,
    "tag": "network security breach",
    "macro_tag_id": -302,
    "macro_tag": "Network Intrusion",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 14,
    "tag_trend_rank": 1,
    "tag_momentum": -1
  },
  {
    "analytic_interval": "2015-05-29T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 3025,
    "tag": "distributed denial-of-service",
    "macro_tag_id": -301,
    "macro_tag": "Network Attack",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 10,
    "tag_trend_rank": 2,
    "tag_momentum": 0
  },
  {
    "analytic_interval": "2015-05-29T00:00:00.000Z/2015-06-28T00:00:00.000Z",
    "analytic_day": "2015-06-28T00:00:00.000Z",
    "feed_id": -3,
    "feed_description": "Financials",
    "tag_id": 154974,
    "tag": "Tinba banking trojan",
    "macro_tag_id": -300,
    "macro_tag": "Malware",
    "tag_super_type_id": 3,
    "tag_super_type": "Practice",
    "tag_trend": 10,
    "tag_trend_rank": 3,
    "tag_momentum": 0
  }
]

Payload Object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
analytic_day Interval The datetime interval over which the analytic was run.
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_trend float The percentage of activity of a Cyber Tag within a Macro Tag category for a particular Feed.
tag_trend_rank float Indicates the rank of a Cyber Tag's activity within a Macro Tag category for a particular Feed.
tag_momentum float Indicates decreased, unchanged, or increased (-1, 0, 1) Cyber Tag activity within a Macro Tag category for a particular Feed.

Response Format

On success, the response status code is 200 OK and the response body contains an array of Tag Trend objects in JSON format.

On an authentication error, the response status code is 403 Forbidden and the response body contains a single Error Code object in JSON format.

On error, the response status code is an error code and the response body contains a single Error Code object in JSON format.