[Cisco Umbrella] Create an administrator user in your Umbrella organization. Provide a JSON object body with required fields firstname, lastname, email, and roleId (from umb_list_roles); optional password and timezone. The body contains a password — handle it as a secret. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete an administrator user from your Umbrella organization by userId (from umb_list_users). This permanently removes the user. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single administrator user by id. Returns the user's full detail (name, email, role, status). Discover userId with umb_list_users.

[Cisco Umbrella] List the administrator roles available in your Umbrella organization. Returns each role's id and label. Use the returned roleId when creating an administrator with umb_create_user.

[Cisco Umbrella] List the administrator users in your Umbrella organization. Returns each user's id, name, email, and role. Paginated with page + limit (limit capped at 1000). Use umb_get_user for one user's full detail and the returned userId with umb_delete_user.

[Cisco Umbrella] Rotate the S3 bucket access key for your organization's managed S3 log storage. This mints a NEW secretAccessKey and immediately invalidates the previous one — the response returns the new secretAccessKey, so handle it as a secret / credential material. Cisco mandates rotating this key at least every 90 days. Takes no parameters. Vendor scope: Admin > IAM (admin.iam:write). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Create an API key. Provide a JSON object body with required fields name and scopes (array of scope strings); optional description, expireAt, and allowedIPs (array of IP addresses / CIDR blocks). Returns the new key and its secret (shown once). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete an API key by apiKeyId (from umb_list_api_keys). This permanently revokes the key. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single API key by apiKeyId (from umb_list_api_keys). Returns the key's name, scopes, allowed IPs, and expiration (never the secret).

[Cisco Umbrella] List the API keys created by your organization. Returns each key's id, name, scopes, and expiration (never the secret). Paginated with limit + offset (limit capped at 1000). Use umb_get_api_key for one key's detail and the returned apiKeyId with umb_update_api_key, umb_delete_api_key, or umb_refresh_api_key.

[Cisco Umbrella] Refresh an API key, rotating its secret. Identify the key by apiKeyId (from umb_list_api_keys); no request body. Returns the key with its new secret (shown once). WARNING: rotating a key immediately invalidates its current secret, so EVERY consumer of that key stops working until it is reconfigured with the new secret — no in-use key is safe to rotate blindly. Rotating the key StackJack itself uses for this Umbrella connector is a known self-outage: the one-time secret Umbrella returns is NOT saved back to StackJack's stored connector credentials, so you must manually re-save it in the Portal to restore access. Rotating any OTHER in-use key (other integrations, scripts, dashboards) likewise breaks those consumers until each is updated with the new secret wherever the key is consumed. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Update an API key's name, description, scopes, and allowed IPs. Identify the key by apiKeyId (from umb_list_api_keys) and provide a JSON object body with required fields name and scopes (array); optional description and allowedIPs (array). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Create an internal network. Provide a JSON object body with required fields name, ipAddress, and prefixLength; optional siteId, networkId, and tunnelId to associate it (discover those with umb_list_sites, umb_list_networks, and the tunnels tools). A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Create a network (external/egress IP range). Provide a JSON object body with required fields name, prefixLength, isDynamic, and status; optional ipAddress. Note: before creating a network you must contact Cisco Support to get your IP range verified. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete an internal network by its origin id (internalNetworkId, from umb_list_internal_networks). This permanently removes the internal network. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete a network by networkId (from umb_list_networks). This permanently removes the network from your deployment. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single internal network by its origin id (internalNetworkId, from umb_list_internal_networks). Returns the internal network's name, IP address/prefix, and associations.

[Cisco Umbrella] Get a single network by networkId (from umb_list_networks). Returns the network's name, IP address/prefix, dynamic flag, and status.

[Cisco Umbrella] List the policies applied to an internal network by its origin id (internalNetworkId, from umb_list_internal_networks). Optional type selects the policy family — dns or web. Vendor scope: deployments.internalnetworks:read.

[Cisco Umbrella] List the internal networks defined in your Umbrella deployment. Returns each internal network's id, name, IP address/prefix, and any associated site/network/tunnel. Optionally filter by name. Paginated with page + limit (limit capped at 1000). Use umb_get_internal_network for one record's detail and the returned id with umb_update_internal_network or umb_delete_internal_network.

[Cisco Umbrella] List the policies applied to a network by its networkId (from umb_list_networks). Optional type selects the policy family — dns or web. Vendor scope: deployments.networks:read.

[Cisco Umbrella] List the networks (external/egress IP ranges) registered in your Umbrella deployment. Returns each network's id, name, IP address/prefix, and status. Paginated with page + limit (limit capped at 1000). Use umb_get_network for one network's detail and the returned networkId with umb_update_network or umb_delete_network.

[Cisco Umbrella] Update an internal network. Identify it by its origin id (internalNetworkId, from umb_list_internal_networks) and provide a JSON object body with required fields name, ipAddress, and prefixLength; optional siteId, networkId, and tunnelId. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Update a network. Identify it by networkId (from umb_list_networks) and provide a JSON object body with required fields name, isDynamic, and status; optional ipAddress and prefixLength. Note: before changing the network's IP address you must contact Cisco Support to get your IP range verified. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Create a site. Provide a JSON object body with the required field name. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete a site by siteId (from umb_list_sites). This permanently removes the site. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single site by siteId (from umb_list_sites). Returns the site's name and origin id.

[Cisco Umbrella] List the sites in your Umbrella organization. Returns each site's id, name, and origin id. Paginated with page + limit (limit capped at 1000). Use umb_get_site for one site's detail and the returned siteId with umb_update_site or umb_delete_site.

[Cisco Umbrella] Update a site. Identify it by siteId (from umb_list_sites) and provide a JSON object body with the required field name. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Add a new network tunnel to the organization. Provide the tunnel as a JSON object in fieldsJson — required: name; optional: siteOriginId, deviceType, serviceType, networkCIDRs, transport, authentication (data-center choices come from umb_list_tunnel_datacenters). A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.

[Cisco Umbrella] Permanently delete a network tunnel by its numeric id (from umb_list_tunnels). If the tunnel is attached to policies, set detachPolicies=true to detach it during deletion. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Get a single network tunnel by its numeric id (from umb_list_tunnels). Returns the tunnel's full configuration including name, siteOriginId, device/service type, network CIDRs, transport, and authentication metadata.

[Cisco Umbrella] Get recent events for a network tunnel by its numeric id (from umb_list_tunnels). Optional hour (1-168) selects the lookback window, limit (1-500, capped at 500) caps the page size, and cursor pages forward. Returns a single {meta,data} object. Vendor scope: deployments.tunnels:read.

[Cisco Umbrella] Get global events for a network tunnel (by numeric id, from umb_list_tunnels) filtered to a specific source IP. The ip is a required path segment. Optional hour (1-168), limit (1-500, capped at 500), and cursor page forward. Returns an array of {meta,data} objects. Vendor scope: deployments.tunnels:read.

[Cisco Umbrella] List the IPsec-enabled Umbrella data centers available for tunnel termination. Each entry includes the data center's IP address and location details — use these when choosing a data center for umb_create_tunnel.

[Cisco Umbrella] List the policies attached to a network tunnel by its numeric id (from umb_list_tunnels). Optional type selects the policy family — firewallrule or web (note: this endpoint uses firewallrule|web, NOT dns|web). Page with page + limit (limit capped at 1000). Vendor scope: deployments.tunnels:read.

[Cisco Umbrella] List the live state information for all network tunnels in the organization (up/down status and connection details across every tunnel). For one tunnel's state, use umb_get_tunnel_state.

[Cisco Umbrella] List the network tunnels (IPsec) configured for the organization. Returns each tunnel's id, name, device/service type, data center, and status. Set includeState=true to embed live tunnel state. Cursor pagination: pass a bounded limit and, to page, the startKey returned in the Link header of the prior response. Use filters (a JSON object string) to narrow by name/deviceType/serviceType/status/dataCenter/siteOriginId. Tunnel ids feed umb_get_tunnel, umb_update_tunnel, and umb_delete_tunnel.

[Cisco Umbrella] Rotate the IPsec pre-shared key (PSK) credentials for a network tunnel by its numeric id (from umb_list_tunnels). Provide a JSON object in fieldsJson — required: autoRotate (boolean); when autoRotate is false you MUST supply psk.idPrefix. Optional deprecateCurrentKeys=true deletes the current key immediately; otherwise the current PSK is invalidated but retained for 24h. WARNING: this invalidates the current PSK and RETURNS THE NEW SECRET in the response (treat it as credential material). Vendor scope: deployments.tunnels:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Update a network tunnel by its numeric id (from umb_list_tunnels). Provide the changes as a JSON object in fieldsJson — required: name and client; updatable: name, siteOriginId, networkCIDRs, client (deviceType). Updates to read-only attributes are ignored. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Add (create) an internal domain. Provide a JSON object body with the required field domain; optional description, includeAllVAs (bool), includeAllMobileDevices (bool), and siteIds (array of site ids from umb_list_sites). If you omit siteIds, the internal domain is associated with all sites in the organization. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Delete an internal domain by internalDomainId (from umb_list_internal_domains). This permanently removes the internal domain. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single internal domain by internalDomainId (from umb_list_internal_domains). Returns the domain, description, and site associations.

[Cisco Umbrella] List the internal domains configured for your Umbrella deployment (domains excluded from DNS redirection). Returns each internal domain's id, domain, description, and site associations. Paginated with page + limit (limit capped at 1000). Use umb_get_internal_domain for one record's detail and the returned id with umb_update_internal_domain or umb_delete_internal_domain.

[Cisco Umbrella] Update an internal domain. Identify it by internalDomainId (from umb_list_internal_domains) and provide a JSON object body with the required field domain; optional description, includeAllVAs (bool), includeAllMobileDevices (bool), and siteIds (array of site ids). A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Associate a device tag with one or more devices. Provide tagId (from umb_list_tags) and originIdsJson, a JSON array of device originIds to tag, e.g. [12345,67890]. Shares its endpoint with umb_remove_tags_from_devices; this tool sends the addOrigins body key. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Register a new network device (integrated router/firewall, e.g. Cisco ISR) in the organization. Provide the device as a JSON object in fieldsJson — required: model, macAddress (12 hex chars, no separators), name (1-50 chars), serialNumber. Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.

[Cisco Umbrella] Create a new device tag in the organization. Provide the tag as a JSON object in fieldsJson — required: name (the tag label), e.g. {"name":"finance-laptops"}. The returned tag id is used by umb_add_tags_to_devices. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Permanently delete (deregister) a network device from the organization by its numeric originId (from umb_list_network_devices). Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Permanently delete (deregister) a roaming computer from the organization by its deviceId (from umb_list_roaming_computers). A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.

[Cisco Umbrella] Permanently delete a virtual appliance (VA) from the organization by its numeric originId (virtualApplianceId, from umb_list_virtual_appliances). Vendor scope: deployments.virtualappliances:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Get a single network device by its numeric originId (from umb_list_network_devices). Returns the device's full detail.

[Cisco Umbrella] Get a single roaming computer by its deviceId (from umb_list_roaming_computers). Returns the device's full detail including DNS-layer and SWG status.

[Cisco Umbrella] Get organization-level roaming-computer information (org-wide roaming deployment metadata). Takes no parameters. Vendor scope: deployments.roamingcomputersOrgInfo:read — a plain deployments.roamingcomputers:read key returns 403 for this endpoint.

[Cisco Umbrella] Get a single Umbrella virtual appliance by its numeric originId (from umb_list_virtual_appliances). Returns the VA's full configuration and status.

[Cisco Umbrella] List the policies applied to a network device by its numeric originId (from umb_list_network_devices). Optional type selects the policy family — dns or web (the server defaults to dns). Vendor scope: deployments.networkdevices:read.

[Cisco Umbrella] List the network devices (integrated routers/firewalls, e.g. Cisco ISR) registered in the organization. Returns each device's originId, name, and model. Use umb_get_network_device for one device's detail.

[Cisco Umbrella] List the roaming computers (Umbrella roaming client / SWG module devices) in the organization. Returns each computer's deviceId, name, DNS-layer status, and SWG (Secure Web Gateway) status. Filter by name, status (DNS-layer), swgStatus, and lastSync window (lastSyncBefore / lastSyncAfter timestamps). Page-based pagination. deviceId feeds umb_get_roaming_computer and umb_delete_roaming_computer.

[Cisco Umbrella] List the device tags defined in the organization. Returns each tag's id and name. Tag ids feed umb_add_tags_to_devices and umb_remove_tags_from_devices. Page-based pagination (page + limit).

[Cisco Umbrella] List the Umbrella virtual appliances (VAs) deployed in the organization. Returns each VA's originId, name, version, and status. Page-based pagination (page + limit). VA originIds identify these devices as identities in umb_add_identity_to_policy.

[Cisco Umbrella] Remove a device tag association from one or more devices. Provide tagId (from umb_list_tags) and originIdsJson, a JSON array of device originIds to untag, e.g. [12345,67890]. Issues an HTTP DELETE on the shared /tags//devices path (the add sibling is a POST) with the removeOrigins body key. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Update a network device by its numeric originId (from umb_list_network_devices). Issues an HTTP PATCH; provide the changes as a JSON object in fieldsJson — required: name. Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Update a roaming computer by its deviceId (a hex string, from umb_list_roaming_computers). Provide the changes as a JSON object in fieldsJson — required: name. Vendor scope: deployments.roamingcomputers:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Update a virtual appliance (VA) by its numeric originId (virtualApplianceId, from umb_list_virtual_appliances). Issues an HTTP PUT; provide the changes as a JSON object in fieldsJson — required: siteId. Vendor scope: deployments.virtualappliances:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.

[Cisco Umbrella] Add destination entries to a destination list, identified by its numeric id (from umb_list_destination_lists). Provide destinationsJson, a JSON array of objects — each requires destination (a domain, URL, or IP) and optionally a comment, e.g. [{"destination":"badsite.com","comment":"phishing"}]. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.

[Cisco Umbrella] Create a destination list (allow or block list) in the organization. Provide the list as a JSON object in fieldsJson — required: access ("allow" or "block"), isGlobal (bool), name; optional: bundleTypeId, destinations (array of {destination, comment}). A 403 means the API key lacks the policies write scope — re-issue the Umbrella API key with edit:policies.

[Cisco Umbrella] Permanently delete a destination list from the organization by its numeric id (from umb_list_destination_lists). A 403 means the API key lacks the policies write scope — re-issue the Umbrella API key with edit:policies.

[Cisco Umbrella] Get a single destination list by its numeric id (from umb_list_destination_lists). Returns the list's metadata (name, access, isGlobal, bundleTypeId, destination count). For the entries themselves, use umb_list_destinations.

[Cisco Umbrella] List the destination lists (allow/block lists) in the organization. Returns each list's id, name, access (allow|block), and destination count. List ids feed umb_get_destination_list, umb_list_destinations, umb_update_destination_list, umb_delete_destination_list, umb_add_destinations, and umb_remove_destinations. Page-based pagination (page + limit).

[Cisco Umbrella] List the destination entries (domains, URLs, or IPs) inside a destination list, identified by its numeric id (from umb_list_destination_lists). Returns each entry's id, destination, type, and comment. The entry ids are what umb_remove_destinations deletes. Page-based pagination (page + limit).

[Cisco Umbrella] Remove destination entries from a destination list, identified by its numeric id (from umb_list_destination_lists). Provide destinationsJson, a JSON array of destination entry ids (NOT the domains) to delete, e.g. [123,456] — retrieve these ids via umb_list_destinations. Accepts at most 500 ids per call. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.

[Cisco Umbrella] Rename a destination list by its numeric id (from umb_list_destination_lists). Provide the change as a JSON object in fieldsJson — required: name. To change the entries, use umb_add_destinations / umb_remove_destinations instead. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.

[Cisco Umbrella] Add an identity to a deployment policy. Provide policyId (from umb_list_deployment_policies) and the identity's originId (e.g. a network, roaming computer, virtual appliance, or network device origin id). No request body. Policy changes may take up to 20 minutes to take effect globally. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.

[Cisco Umbrella] List the Umbrella deployment policies. Returns each policy's id, name, and type. Filter by type ("dns" or "web"); when omitted, Umbrella returns DNS policies. Policy ids feed umb_add_identity_to_policy and umb_remove_identity_from_policy. Page-based pagination (page + limit).

[Cisco Umbrella] Remove an identity from a deployment policy. Provide policyId (from umb_list_deployment_policies) and the identity's originId. No request body. Policy changes may take up to 20 minutes to take effect globally. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.

[Cisco Umbrella] List the identities known to Umbrella reporting (used to interpret and filter other reports). Optional search string and identitytypes (comma-delimited identity types) narrow the results. Page with limit (bounded; the server returns at most 5000 records) + offset. Access Scope: Reports > Utilities > Read-Only.

[Cisco Umbrella] List all activity events (DNS, proxy, firewall, intrusion) within a time window. The IP activity report is not available here. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List granular AMP retrospective (post-hoc malware detection) activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with ampdisposition, sha256, and timezone filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List DNS activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List firewall activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with categories, verdict, identityids, ip, ports, and ruleid filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List granular intrusion (IPS) activity events within a time window. Requires the firewall-IPS package; without it the endpoint returns 403 or an empty result set (a data-availability concern, not a connector error). from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with identityids, signatures, signaturelistids, intrusionaction, ip, ports, filternoisydomains, and timezone filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List granular IP-layer activity events within a time window. Deprecated in the Umbrella spec (the legacy IP Enforcement Layer) but still served on the current v2 surface. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with identityids, identitytypes, categories, verdict, ip, and ports filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] List proxy (secure web gateway) activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.

[Cisco Umbrella] Get an aggregate summary report (request totals with category and threat rollups) for a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. offset paginates. Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the threat types Umbrella recognizes (a reference lookup; no time window or pagination). Use the returned type identifiers to interpret threat-type fields in other reports such as umb_report_top_threats. Access Scope: Reports > Utilities > Read-Only.

[Cisco Umbrella] List the content/security categories that received the most requests in a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. offset paginates. Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the top DNS destinations (domains) by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the top firewall destinations by connection/request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the top IP-layer (IP enforcement) destinations by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the top proxy destinations by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the identities that made the most requests within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the top IP addresses by request volume within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the top threats (both DNS and proxy) within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the total count of requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the total count of DNS requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the total count of firewall events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the total count of IP-layer (IP enforcement) requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] Get the total count of proxy requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.

[Cisco Umbrella] List the identities (users/devices) observed using a discovered application. applicationId comes from umb_appdiscovery_list_applications. Page with limit (bounded) + offset. Use this to see who is using a given cloud app. Access Scope: Reports > Read-Only.

[Cisco Umbrella] Get the risk assessment for a single discovered application: its risk score and the contributing risk attributes used to triage Shadow IT / SaaS exposure. applicationId comes from umb_appdiscovery_list_applications. Access Scope: Reports > Read-Only.

[Cisco Umbrella] Get a single discovered cloud application by id, including its metadata used to triage Shadow IT / SaaS exposure. applicationId comes from umb_appdiscovery_list_applications. Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] Get a single application protocol by id. protocolId comes from umb_appdiscovery_list_protocols. Optionally pass date (YYYY-MM-DD) to report as of a specific day. Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] List the attributes (security/compliance/business characteristics) of a discovered application. applicationId comes from umb_appdiscovery_list_applications. Optionally filter by categories (comma-separated). Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] List the application categories used to classify discovered cloud apps. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] List cloud applications discovered in your Umbrella traffic (App Discovery / Shadow IT report). Each application carries an id required by umb_appdiscovery_get_app_risk, umb_appdiscovery_get_app_identities, and umb_appdiscovery_update_app_label. Optionally pass date (YYYY-MM-DD) to report as of a specific day; omit for the latest data. Page with limit (bounded) + offset. Access Scope: Reports > Read-Only.

[Cisco Umbrella] List the identities (users/devices) observed using a given application protocol. protocolId comes from umb_appdiscovery_list_protocols. Optionally pass date (YYYY-MM-DD) and sort with sort/order. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] List cloud application protocols observed in your Umbrella traffic. Optionally filter by identity and sort with sort/order. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).

[Cisco Umbrella] Set the review label / status on a discovered application (for example approve or tag it). applicationId comes from umb_appdiscovery_list_applications. Body (required): label. A 403 means the Umbrella API key lacks the reports write scope — re-issue the key with edit access to App Discovery.

[Cisco Umbrella] Bulk-set the review label / status on many discovered applications at once (collection-level PATCH — distinct from the single-item umb_appdiscovery_update_app_label). Body (required): label (the review label to apply) and applicationsList (array of 1..1000 application ids). A 403 means the Umbrella API key lacks the App Discovery write scope — re-issue the key with reports.appDiscovery:write.

[Cisco Umbrella] List Umbrella API usage attributed per API key over a date window (which keys made how many calls). from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Use this to attribute consumption to individual keys discovered via umb_list_api_keys. Access Scope: Reports > Read-Only.

[Cisco Umbrella] List Umbrella API request counts over a date window, broken down by request. from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Companion to umb_apiusage_summary (totals) and umb_apiusage_responses (status-code breakdown). Access Scope: Reports > Read-Only.

[Cisco Umbrella] List Umbrella API response counts over a date window, broken down by HTTP response/status code. from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Use this to spot elevated error rates (4xx/5xx) in your API traffic. Access Scope: Reports > Read-Only.

[Cisco Umbrella] Get an aggregate summary of your organization's Umbrella API usage (total request counts and rollups) over a date window. from/to are calendar dates in YYYY-MM-DD format and are passed through verbatim (do not reformat). Use this to gauge overall API consumption before drilling into umb_apiusage_requests, umb_apiusage_responses, or umb_apiusage_keys. Access Scope: Reports > Read-Only.

[Cisco Umbrella] Get the CIDR prefixes and geo information advertised by an Autonomous System Number (ASN). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Get Autonomous-System information for an IPv4 address (ASN, CIDR, RIR, and owner/description). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Provide a list of domains and look up the status, and security and content category IDs for each domain. The domain status is a numerical value determined by the Cisco Security Labs team. Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status). Requires the Umbrella Investigate add-on license; calls return 403/404 without it. Body: {"domains": ["example.com", ...]} (Tier 2/3 only).

[Cisco Umbrella] Look up the status, and security and content category IDs for the domain. The domain status is a numerical value determined by the Cisco Security Labs team. Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status). Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] The Investigate Risk Score is based on an analysis of the lexical characteristics of the domain name and patterns in queries and requests to the domain. The risk score is scaled from 0 to 100 where 100 is the highest risk and 0 represents no risk at all. Periodically, Investigate updates this score based on additional inputs. A domain blocked by Umbrella receives a score of 100. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List multiple scores or security features for a domain. You can use the scores or security features to determine relevant data points and build insights on the reputation or security risk posed by the site. No one security information feature is conclusive. Instead, consider these features as part of your security research. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the query volume for a domain over the last 30 days. If there is no information about the domain, Investigate returns an empty array. As the query takes time to generate, the last two hours may be blank. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List domains that co-occur within a small time window of the given domain (the true co-occurrence 'links' endpoint). No pagination. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] The Passive DNS endpoint provides historical data from the Umbrella resolvers for domains, IPs, and other resource records. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata) is the domain(s). Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Get Passive-DNS Resource Records matching raw rdata (for example TXT record contents). URL-encode the value; wrap TXT strings in quotes. Page with limit + offset (bounded, capped at 1000; default 500). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Get Passive-DNS Resource Records (RRs) where the answer/rdata is the given domain — the answer-side view, distinct from umb_investigate_pdns_domain which returns query-side RRs on /pdns/name. Page with limit + offset (bounded, capped at 1000; default 500). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the co-occurences for the specified domain. A co-occurrence is when two or more domains are accessed by the same users within a small window of time. Co-occurring domains are not necessarily problematic; legitimate sites co-occur with each other as a part of normal web activity. However, unusual or suspicious co-occurences can provide additional information regarding attacks. To determine co-occurrences for a domain, a small time window of traffic across all of our datacenters is taken. Investigate checks the sites that end users visited before and after the domain was requested in the API call. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Specify a domain, IP, or URL. Use the destination to search for all samples associated with the destination. The default number of items in a response is 10. You can extend the limit. You must have a license for Cisco Secure Malware Analytics to receive the samples data. Cisco Secure Malware Analytics retains checksum samples for one year. You may find that Investigate previously listed a sample related to a destination. If Cisco Secure Malware Analytics no longer contains a sample related to the destination, Investigate does not display the sample in the list of associated samples. An error may occur when the requested destination is not in a valid format, if the requested host is not found in our database, or if there is no data available for the destination that you have requested. CIDR subnets (for example: 10.10.10.0/24) and pattern search is not supported. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the newly seen domains that match a regular expression pattern. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List known subdomains of a domain. limit is capped at 100 (default 20); use offsetName (the last subdomain from the previous page) as the pagination cursor. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the historical tagging timeline for a given IP, domain, or URL. Investigate sorts the timeline items in descending order using the timestamp field. Each timeline item includes lists of security category, attack, or threat type associated with the destination. Use the Tagging Timeline endpoint to verify when Umbrella assigned or removed a security category, attack, or threat type. If the current timeline item contains the security category, type of attack, or threat type not found in the previous timeline item, Umbrella updated the current timeline item. If the current timeline item does not contain the security category, attack, or threat type found in the previous timeline item, Umbrella removed the security category, type of attack, or threat type. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the most seen domains in Umbrella. You can download the data in a zip file, or use the Investigate API to stream the data into a SIEM. The popularity list contains our most queried domains based on passive DNS usage across our Umbrella global network of more than 180 billion requests per day with many tens of millions of unique active users, in more than 165 countries. The metric does not only consist of browser-based http requests from users but also takes in to account the number of unique client IPs invoking this domain relative to the sum of all requests to all domains. Our popularity ranking reflects the domain's relative internet activity agnostic to the invocation protocols and applications where as site ranking models (such as Alexa) focus on the web activity over port 80 (primarily from browsers). In addition, the Umbrella popularity algorithm also applies data normalization techniques to smooth potential biases that may occur due to sampling of DNS usage data. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Get the WHOIS information for the specified email addresses, nameservers, and domains. You can search by multiple email addresses or multiple nameservers. This documentation outlines the following API endpoints: email (single and multiple), domain record (current and historical), and nameserver (single and multiple). In some instances, WHOIS information can be irregular as there are no standards between domain registrars and large volumes of information can be returned from a query. As such, both the email and nameserver WHOIS endpoints have a limit of 500 results, which you can reduce to a smaller set of results. There is an `offset` parameter that can be leveraged to retrieve the entire set of domain entries for a given email without any limitation. Only the email parameter supports this. You can sort the email parameter by filtering the entries based on the timestamp field. If a domain, email, or nameserver has no known WHOIS information, Investigate returns `HTTP 404`. If a domain, email or nameserver does not exist, Investigate returns `HTTP 404`. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the domains registered by a registrant email address. WHOIS caps at 500 results per request; use offset to page past 500 (email is the one endpoint that pages the full set). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List historical WHOIS records for a domain. Default 10 records. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the domains registered against a SINGLE nameserver (path parameter). WHOIS endpoints cap at 500 results; use offset to page. Distinct from umb_investigate_whois_nameservers (batch query). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] List the domains registered against a BATCH of nameservers. The required nameServerList is a comma-delimited list of nameserver hostnames. WHOIS endpoints cap at 500 results; use offset to page. Distinct from umb_investigate_whois_nameserver (single, path-param). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Regex-search WHOIS records by field (for example 'nameservers' or 'emails') matching a regular-expression pattern. start is REQUIRED and the search window is at most 30 days. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.

[Cisco Umbrella] Create a customer under the Managed Providers (Multi-Org/MSP) console. Provide a JSON object body — required: customerName (string 1-255) and seats (integer >= 1). Requires a Managed-Provider/MSP-console API key; a 403 means the key lacks the admin.customers:write scope (or is not a provider-tier key) — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Permanently delete a Managed Providers customer by customerId (from umb_list_managed_customers). This cannot be undone. A 403 means the API key lacks the admin.customers:write scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Get a single Managed Providers customer by customerId (from umb_list_managed_customers). Returns customerId, customerName, and seats.

[Cisco Umbrella] List the customers under your Umbrella Managed Providers (Multi-Org/MSP) console. Returns an array of customers, each with customerId, customerName, and seats. Paginated with page + limit (limit max 100). Use umb_get_managed_customer for one customer and the returned customerId with umb_update_managed_customer / umb_delete_managed_customer.

[Cisco Umbrella] Update a Managed Providers customer by customerId (from umb_list_managed_customers). Provide a JSON object body — required: customerName (string 1-255) and seats (integer >= 1); both must be supplied. A 403 means the API key lacks the admin.customers:write scope — re-issue the Umbrella API key with that scope.

[Cisco Umbrella] Create a Service-Provider customer. Provide a JSON object body — required: customerName (1-255), seats (>=1), streetAddress, city, countryCode (2-3), packageId (171/202/246/248/250/252/312), adminEmails (array of email). Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails, addonRbi ('0'-'3'), addonCdfwL7, addonDlp, licenseType ('term'/'msla'), isTrial. A 403 means the API key lacks admin.customers:write or is not a provider-console key.

[Cisco Umbrella] Permanently delete a Service-Provider customer by customerId. Returns 204 (no content). Cannot be undone. A 403 means the API key lacks admin.customers:write.

[Cisco Umbrella] Get one Service-Provider customer by customerId (from umb_list_provider_customers). Returns the full customer object. Requires a provider-console key with admin.customers:read.

[Cisco Umbrella] List the packages available when creating a Service-Provider customer. Returns an array of {id, name, pkgSeatMin, ppovSeatMin}. Use a returned id as packageId in umb_create_provider_customer. Requires a provider-console key with admin.customers:read.

[Cisco Umbrella] Get subscription details for a Service-Provider customer by customerId — package, seats, start/end dates, trial lifecycle, access-request state. (createdAt/modifiedAt here are epoch-seconds integers, e.g. 1594557263; note the top-level Customer schema instead uses ISO-8601 strings for these fields.) Requires a provider-console key with admin.customers:read.

[Cisco Umbrella] List the customers under your Umbrella Service-Provider/MSSP console. Returns an array of customers (customerId, customerName, packageName/packageId, seats, address, adminEmails, addons). Paginated with page + limit (max 100). Requires a provider-console key with admin.customers:read. A 403/404 means the API key lacks that scope or is not a provider-console key.

[Cisco Umbrella] Update a Service-Provider customer by customerId (full replace). JSON body — required: customerName, seats, streetAddress, city, countryCode, packageId, adminEmails. Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails. Note: the update body does NOT accept licenseType/isTrial/addonRbi/addonCdfwL7/addonDlp (response-only fields). A 403 means the API key lacks admin.customers:write.

[Cisco Umbrella] Irreversibly convert a trial to a paying customer by customerId. Provide a JSON object body — required: packageId (one of 246/248/250/252). Returns . This changes billing state and cannot be undone. Requires admin.customers:write on a provider-console key. (Vendor example shows 107 but the enum is [246,248,250,252] — send an enum value.)

[Cisco Umbrella] Request delegated access to a customer's Umbrella org by customerId. No request body (built from the path and provider identity). Returns the AccessRequest object. Requires admin.customers:write on a provider-console key.

[Cisco Umbrella] Extend a customer's trial by customerId. Provide a JSON object body — trialExtensionDays (must be 7 or 14). Returns the full customer object. Requires admin.customers:write on a provider-console key.

[Cisco Umbrella] Get a delegated-access request by customerId and accessRequestId. Returns the request object (id, organizationId, state = approved/denied/pending, organizationName, timestamps). Requires a provider-console key with admin.customers:read.

[Cisco Umbrella] Get a trial customer's engagement strength by customerId — customerLoggedIn, lastLoginDate, identitiesCreated, hasTraffic, trialStrength (Low/Medium/High/-). Requires a provider-console key with admin.customers:read.

[Cisco Umbrella] Advance a delegated-access request's state by customerId and accessRequestId. No request body — the transition is a server-side action driven by the path, so a repeat call is not guaranteed to be a no-op. Returns the updated AccessRequest. Requires admin.customers:write on a provider-console key.

[Cisco Umbrella] Get a customer deal by dealId. Required query ccoId (integer — the CCO id of the querying user). Returns an array of CustomerDeal objects (Cisco returns array shape even for get-by-id). Requires a provider-console key with admin.customerDeals:read; a 403 means the key lacks that scope or is not a provider-console key.

[Cisco Umbrella] List Service-Provider customer addresses. Paginated with page + limit (max 100). Returns an array of {accountId, accountSiteId, mappedCrPartyId, organizationName, address fields}. Requires a provider-console key with admin.customerSearch:read; a 403 means the key lacks that scope.

[Cisco Umbrella] List the organizations visible to a provider-org member. Required query email (a member of the provider org). Optional page/offset/limit (max 100). Returns an array of {organizationId, organizationName, mspOrganizationId, organizationTypeId, ...}. A 404 means the email was not found. Requires a provider-console key with admin.organizations:read.

[Cisco Umbrella] Force a password reset for named admin accounts in a child (customer) org by customerId. Provide a JSON object body — required: adminEmails (array of the child-org user emails to reset). This irreversibly invalidates those users' current passwords and triggers a reset flow. 200 returns an empty body. Requires a parent (provider) org token with admin.passwordreset:write; a 403 means the key lacks that scope or is not a provider-console key.

[Cisco Umbrella] Update a customer deal by dealId (full replace). Provide a JSON object body — required: ccoid (integer), customerId (integer); optional: quoteId (integer), majorLineItems (array of {objectId, sourceAppRefId}). NB casing: the write op carries ccoid in the body (the read uses ccoId in the query). Requires admin.customerDeals:write; a 403 means the key lacks that scope or is not a provider-console key.