Getting Started
The Umbrella Console Reporting v1 API follows RESTful principles and uses JSON for all requests and responses.
Base URI
The Umbrella Console Reporting v1 API begins with the following base URI:
https://reports.api.umbrella.com/v1
Authentication
The Umbrella Console Reporting v1 API uses HTTP Basic authentication. Include your Umbrella Reporting API credentials in a request to the Umbrella Console Reporting v1 API. For information about creating a legacy Umbrella API key, see Authentication.
Authorization
The Umbrella Console Reporting v1 API requires an Authorization header and uses Basic authentication.
Encode Your API Credentials
You can run one of the sample scripts to encode your credentials.
echo -n '<key>:<secret>' | openssl base64
[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('<key>:<secret>'))
#!/usr/bin/env python
import base64
# Substitute your key and secret.
credentialStr = '<key>:<secret>'
# Encode and print your credentials
print(base64.b64encode(credentialStr))
Add Encoded Credentials to Authorization Header
Create a request and set your encoded credentials in the request Authorization header.
curl -i GET 'https://reports.api.umbrella.com/v1/organizations/{consoleId}/detailed-summary' \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'
Migrate to Reporting v2 API
We recommend that you migrate to the Umbrella Reporting v2 API. The following tables describe how you can substitute a Reporting v2 API endpoint for a Console Reporting v1 API endpoint, and return a similar set of reporting data. For more information about the Umbrella Reporting v2 API, see Getting Started with Umbrella Reporting v2 API.
Note: The Summary and Deployment Status API data is available only for a 24 hour time period. You cannot extend the time period of the report.
Detailed Summary
| Endpoint Name | API Version | Endpoint Path |
|---|---|---|
| Detailed Summary | Console Reporting v1 | /organizations/{consoleId}/detailed-summary |
| MSP Deployment Status | Reporting v2 | /providers/{mspOrganizationId}/deployments |
Security Summary
| Endpoint Name | API Version | Endpoint Path |
|---|---|---|
| Security Summary | Console Reporting v1 | /organizations/{consoleId}/security-summary |
| MSP Requests by Organization | Reporting v2 | /providers/{mspOrganizationId}/requests-by-org |
Pagination
The Umbrella Console Reporting v1 API uses query parameters to paginate results in the collection.
| Field | Type | Description |
|---|---|---|
| limit | integer | The number of organizations to return in the collection. The default is 50. |
| offset | integer | A number that represents an index in the collection. The default value is 0. Umbrella lists the organizations in reverse alphabetical order. |
Filtering
The Umbrella Console Reporting v1 API uses query parameters to filter results in the collection.
| Field | Type | Description |
|---|---|---|
| start | integer | A Unix (epoch) timestamp specified in seconds. This timestamp represents the start of the time window. Filter for data that appears after this time. Both the start and end fields must be specified together. |
| end | integer | A Unix (epoch) timestamp specified in seconds. This timestamp represents the end of the time window. Filter for data that appears before this time. Both the start and end fields must be specified together. |
Rate Limits
- 5 requests per minute for all endpoints.
Response Codes
The Umbrella Console Reporting v1 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.
| Status Code | Message | Description |
|---|---|---|
| 200 | OK | Success. Everything worked as expected. |
| 400 | Bad Request | Likely missing a required parameter or malformed JSON. The syntax of your query may need to be revised. Check for any spaces preceding, trailing, or in the domain name of the domain you are trying to query. |
| 401 | Unauthorized | The authorization header is missing or the key and secret pair is invalid. Ensure your API token is valid. |
| 403 | Forbidden | The client is unauthorized to access the content. |
| 404 | Not Found | The requested resource doesn't exist. Check the syntax of your query or ensure the IP and domain are valid. |
| 5xx | Server errors | This request could not be processed by the Umbrella server. |