Getting Started

The Umbrella Investigate API follows standard REST principles and uses JSON for all requests and responses.

Overview

The Umbrella Investigate API provides a complete view of domains in relation to IP and autonomous system number (ASN) information. With the Umbrella Investigate API, you can programmatically collect and analyze the following information:

• Domain status, risk score, and geolocation
• Number of domain searches
• Co-occurring domains
• Subdomains of a domain
• Tagged timeline of a domain, IP, or URL
• Security reputation of a domain
• Top accessed domains
• WHOIS information for the domain
• Threat intelligence data for domains, IPs, and URLs
• Threat intelligence samples by file hash

Umbrella Investigate Add-On for Splunk

The Umbrella Investigate Add-On integrates the Umbrella Investigate API with Splunk. For more information, see Cisco Umbrella Investigate Add-On for Splunk.

Cisco Secure Malware Analytics Integration

Certain Umbrella Investigate API endpoints integrate with Cisco Secure Malware Analytics. These API endpoints provide detailed information about file samples related to an IP, domain, or URL. You must have licenses to both Umbrella Investigate and Cisco Secure Malware Analytics to receive an API response that includes the samples data.

Umbrella Investigate API endpoints that require a Cisco Secure Malware Analytics license:

• GET /samples/{destination}
• GET /sample/{hash}
• GET /sample/{hash}/artifacts
• GET /sample/{hash}/connections
• GET /sample/{hash}/behaviors

Base URI

The Umbrella Investigate API begins with the following base URI:

https://investigate.api.umbrella.com

Authentication

The Umbrella Investigate API uses HTTPS and Bearer token authentication. To get started, log into Umbrella and create an Investigate API token.

Note: API keys, passwords, secrets, and tokens allow access to your private customer data. You should never share your credentials with another user or organization.

Prerequisites

• You must have access to the Investigate role to create and manage an Investigate API token.

Log Into Umbrella

Log into Umbrella with the following URL:

https://dashboard.umbrella.com

In Umbrella, you can find your username after Admin in the navigation tree. Confirm that your organization appears under your username.

Generate API Token

Create an access token.

1. Navigate to Investigate > API Keys.
2. Click Create New Token.
3. Give the token a name, then click Create. The generated token includes the email address of the person who created it and the token creation date. To revoke the token, click the delete icon.

Note: You can create more than one Umbrella Investigate API access token for your organization.

Authorization

The Umbrella Investigate API requires an Authorization header with a Bearer token in every API request. To create an API request, substitute your token in the HTTP Authorization header.

For example:

Copycurl -i GET "https://investigate.api.umbrella.com/domains/categorization/example.com?showlabels" \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Pagination

Many Umbrella Investigate API endpoints provide pagination. Depending on the endpoint, you can set additional query parameters to filter the data in the collection.

The following endpoints support the limit and offset query parameters:

• GET /pdns/name/{domain}
• GET /pdns/domain/{domain}
• GET /pdns/ip/{ip}
• GET /pdns/raw/{anystring}
• GET /whois/emails/{email}
• GET /samples/{domain}
• GET /samples/{ip}
• GET /samples/{url}
• GET /sample/{hash}/artifacts
• GET /sample/{hash}/connections
• GET /sample/{hash}/behaviors

You can add the limit query parameter to these endpoints:

• GET /whois/{domain}/history
• GET /whois/nameservers
• GET /topmillion

Note: If you do not set a limit on the /topmillion collection, Umbrella returns one million records.

Rate Limits

The Umbrella Investigate API has four levels of API access:

• Integration— limited to 2000 requests per day
• Tier 1
• Tier 2
• Tier 3

Depending on your API access tier, the Umbrella Investigate API limits the number of requests for each endpoint. Your organization's API keys share the same rate limit.

Note: When you exceed the rate limit for an endpoint, all additional requests above the limit receive an HTTP 429 response (Too Many Requests) and are discarded. After waiting one second, you can retry your request.

Umbrella Investigate API Endpoints (Group One)

Endpoints:

• /domains/volume/{domain}
• /pdns/name/{domain}
• /pdns/domain/{domain}
• /pdns/ip/{ip}
• /pdns/raw/{anystring}
• /recommendations/name/{domain}.json
• /links/name/{domain}
• /security/name/{domain}
• /bgp_routes/asn/{asn}/prefixes_for_asn.json
• /bgp_routes/ip/{ip}/as_for_ip.json
• /topmillion
• /timeline/{name}
• /subdomains/{domain}

Request Rate Limits:

• Integration— 3 requests per second
• Tier 1— 3 requests per second
• Tier 2— 12 requests per second
• Tier 3— 12 requests per second

Umbrella Investigate API Endpoints (Group Two)

Endpoints:

• /samples/{domain}
• /samples/{ip}
• /samples/{url}
• /whois/{domain}
• /whois/{domain}/history
• /whois/nameservers
• /whois/nameservers/{nameservers}
• /whois/emails/{emails}

Request Rate Limits:

• Integration— 3 requests per second
• Tier 1— 3 requests per second
• Tier 2— 12 requests per second
• Tier 3— 48 requests per second

POST /domains/categorization

API access tiers 2 and 3 support the /domains/categorization POST method.

Request Rate Limits:

• Tier 2— 150 requests per second
• Tier 3— 150 requests per second

Note: The /domains/categorization POST method accepts up to 1000 domains in the request body.

GET /domains/categorization

All API access tiers support the /domains/categorization GET method.

Request Rate Limits:

• Integration— 3 requests per second
• Tier 1— 3 requests per second
• Tier 2— 150 requests per second
• Tier 3— 150 requests per second

GET /search/{expression}

All API access tiers support the /search/{expression} endpoint. The /search/{expression} endpoint defines rate limits based on search complexity. If you use a wildcard prefix, Umbrella searches the entire collection.

Request Rate Limits:

• Searches prefixed with the .* characters- 3 requests per minute
• All other searches— 18 requests per minute

GET /whois/search/{searchField}/{regexExpression}

All API access tiers support the /whois/search/{searchField}/{regexExpression} endpoint.

Request Rate Limits:

• All tiers— 18 requests per minute

Response Codes

The Umbrella Investigate API uses HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with Umbrella's servers.