This is what Mike told me to add.

Domain Status and Categorization

This API method returns the domain status, which the quickest and easiest way to know whether a domain has been flagged as malicious by the Cisco Security Labs team (score of -1 for status), if it is believed to be safe (score of 1), or if it has yet to be given a status (score of 0). When looking to determine whether or not a domain is malicious, the domain status should be considered authoritative over all other Investigate scores.

This method will also return the security categories and content categories of a domain. Categories are the labels or tags Umbrella has given to a domain for the purposes of filtering against that type of domain. The GET request can be returned with numerical or human readable labels for the domains, but a bulk domain lookup with a POST request can only return the numerical label.

A domain can have multiple, overlapping security categories and content categories. For instance, a domain could be both 'Botnet' and 'Malware' if it is deemed to serve malware and also be a command and control. For content, a site could be both 'Dating' and 'Sexuality'.

A list of the numerical identifiers for the categories can be obtained with the following query:

curl -H "Authorization: Bearer %YourToken%"
"https://investigate.api.umbrella.com/domains/categories/"

To query for more than one domain at a time, use the POST example below and post a list of domains as an array. This method will accept up to 1000 domains in a single request.

Sample query for a single domain:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/domains/categorization/example.com"

Sample query for a single domain with human-readable labels:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/domains/categorization/example.com?showLabels"

Sample query for multiple domains:

curl -H "Authorization: Bearer %YourToken%" --request POST "https://investigate.api.umbrella.com/domains/categorization/" -d '["example.net","example.org,","example.com"]'

Parameter for Input

Field
Type
Description

name

string

Domain name

Returned value for output if Success 200

Field
Type
Description

status

integer

The status will be "-1" if the domain is believed to be malicious, "1" if the domain is believed to be benign, "0" if it hasn't been classified yet.

security_categories

array of strings

The Umbrella security category, or categories, that match this domain or that this domain is associated with. If none match, the return will be blank.

content_categories

array of strings

The Umbrella content category or categories that match this domain. If none match, the return will be blank.

GET https://investigate.api.umbrella.com/domains/categorization/amazon.com
REQUEST
curl --include \
    --header "Authorization: Bearer %YourToken%" \
    https://investigate.api.umbrella.com/domains/categorization/amazon.com
    
RESPONSE
{
  "amazon.com": {
    "status": 1,
    "security_categories": [],
    "content_categories": [
      "8"
    ]
  }
}
    
POST https://investigate.api.umbrella.com/domains/categorization/
REQUEST
curl --include \    
    --request POST \    
    --header "Authorization: Bearer %YourToken%" \
    --data-binary "[\"google.com\",\"yahoo.com\"]" \
    https://investigate.api.umbrella.com/domains/categorization
    
RESPONSE (HTTP 200, Content-Type: application/json)
{
  "google.com": {
    "status": 1,
    "security_categories": [],
    "content_categories": [
      "23"
    ]
  },
  "yahoo.com": {
    "status": 1,
    "security_categories": [],
    "content_categories": [
      "23"
    ]
  }
}
    
GET https://investigate.api.umbrella.com/domains/categorization/amazon.com?showlabels
REQUEST
curl --include \
    --header "Authorization: Bearer %YourToken%" \
    https://investigate.api.umbrella.com/domains/categorization/amazon.com?showLabels
    
RESPONSE (HTTP 200, Content-Type: application/json)
{
  "amazon.com": {
    "status": 1,
    "security_categories": [],
    "content_categories": [
      "Ecommerce/Shopping"
    ]
  }
}
    
GET https://investigate.api.umbrella.com/domains/categories/
REQUEST
curl --include \
    --header "Authorization: Bearer %YourToken%"
    https://investigate.api.umbrella.com/domains/categories/
    
RESPONSE (HTTP 200, Content-Type: application/json)
{
    ...
    8: "Ecommerce/Shopping",
    9: "File storage",
    ...
}
--
    

Error Handling < Domain Status and Categorization > Timeline and Classifiers

Updated 11 months ago

Domain Status and Categorization


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.