Umbrella Enforcement API: register domain with event information

Getting Started

The Umbrella Enforcement API follows RESTful principles and uses JSON for all requests and responses.

Base URI

The Umbrella Enforcement API begins with the following base URI:

https://s-platform.api.opendns.com/1.0

Authorization

The Umbrella Enforcement API requests require a customerKey query parameter. For information about creating an Umbrella Enforcement API customer key, see Enforcement API Authentication.

https://s-platform.api.opendns.com/1.0/events?customerKey={customerKey}

Best Practices

  1. Check the state of a domain. When you send a list of domains to the Umbrella Enforcement API, Umbrella checks the reputation of each domain and determines whether to allow or block the domain. For more information, see Register a Domain with Event Information.
  2. List the domains blocked by Umbrella. Check if the domains you registered with the Enforcement API appear in the list of blocked domains. For more information, see List Enforced Domains.

Pagination

The Umbrella Enforcement API uses query parameters to filter a collection. When requesting the list of domains (/domains), you can set the limit and page query parameters.

Note: The default and maximum batch size is 200.

To get another batch size, set the limit query parameter. For example:

Name Type Description
limit number The number of items to return in the collection.
page number The page to start reading in the collection.

Rate Limits

  • Total size of requests must not exceed 1 MB per minute. The size of a request includes the request body, HTTP headers, and URI.
  • No more than 200 domains requested per minute.
  • 5 requests per second.
  • POST requests may contain single or multiple domain events.
  • The maximum length of a domain is 255 characters as established by our data schema and RFC 1034.
  • Exceeding any of these limits results in an HTTP 429 error response.

Response Codes

For information about HTTP response codes, see Umbrella Management API Response Codes.