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 > Domain Scores

Domain Status and Categorization