openapi: 3.2.0
info:
  title: Cisco Umbrella Investigate Security Information for a Domain API
  description: 'The Umbrella Investigate API provides a complete view of domains in relation to IP and autonomous system number (ASN) information.

    You can get the following domain 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'
  version: 2.0.0
  contact:
    name: Cloud Security Developer Community
  x-provenance:
    method: harvested
    authored_by: Cisco Umbrella
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously. Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
  - type: source
    url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
  variables:
    basePath:
      default: investigate/v2
security:
- oauthFlow: []
tags:
- name: Security Information for a Domain
paths:
  /security/name/{domain}:
    get:
      summary: Get Security Score Information for Domain
      operationId: getSecurityName
      tags:
      - Security Information for a Domain
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/domainParam'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: object
                properties:
                  dga_score:
                    type: number
                    description: 'A domain generation algorithm (DGA) is used by malware to generate large lists of domain names.

                      This score is created based on the likeliness

                      of the domain name being generated by an algorithm

                      rather than a human. This algorithm is designed to identify domains which

                      have been created using an automated randomization

                      strategy, which is a common evasion technique in malware kits or botnets.

                      This score ranges from -100 (suspicious) to 0 (benign).'
                    example: 38.301771886101335
                  perplexity:
                    type: number
                    description: 'A second score on the likeliness of the name to be algorithmically

                      generated, on a scale from 0 to 100. This score is used in conjunction with DGA.'
                    example: 0.4540313302593146
                  entropy:
                    type: number
                    description: The number of bits required to encode the domain name as a score. This score is used in conjunction with DGA and Perplexity.
                    example: 2.5216406363433186
                  securerank2:
                    type: number
                    description: 'The suspicious rank for a domain that reviews base on the lookup behavior

                      of client IP for the domain.

                      Securerank is designed to identify hostnames requested by known infected

                      clients but never requested by clean clients,

                      assuming these domains are more likely to be bad.

                      Scores returned range from -100 (suspicious) to 100 (benign).'
                    example: -1.3135141095601992
                  pagerank:
                    type: number
                    description: A popularity score according to Google's PageRank algorithm.
                    example: 0.0262532
                  asn_score:
                    type: number
                    description: The ASN reputation score ranges from -100 to 0 where -100 is very suspicious.
                    example: -29.75810625887133
                  prefix_score:
                    type: number
                    description: 'The prefix ranks domains given their IP prefixes

                      (an IP prefix is the first three octets in an IP address)

                      and the reputation score of these prefixes. The scores range from -100 to 0 where -100 is

                      very suspicious.'
                    example: -64.9070502788884
                  rip_score:
                    type: number
                    description: 'The RIP ranks domains given their IP addresses and the reputation score

                      of these IP addresses. The scores ranges from -100 to 0 where -100 is very suspicious.'
                    example: -75.64720536038982
                  popularity:
                    type: number
                    description: 'The number of unique client IPs visiting this site, relative to all

                      requests to all sites. A score of how many different client or unique IPs requested

                      to this domain compared to others.'
                    example: 25.335450495507196
                  geodiversity:
                    type: array
                    description: The list of scores that represent the number of queries from clients visiting the domain, broken down by country.
                    items:
                      type: number
                      description: 'A score that represents the number of queries from clients visiting the domain,

                        broken down by country. Score is a non-normalized ratio between 0 and 1.'
                      example: 0.24074075
                    example:
                    - 0.24074075
                    - 0.018518519
                  geodiversity_normalized:
                    type: array
                    description: 'The list of scores that represents the amount of queries for clients visiting the domain,

                      broken down by country.'
                    items:
                      type: number
                      description: A score that represents the amount of queries for clients visiting the domain, broken down by country. The score is a normalized ratio between 0 and 1.
                      example: 0.3761535390278368
                    example:
                    - 0.3761535390278368
                    - 0.0005015965168831449
                  tld_geodiversity:
                    type: array
                    description: 'The list of scores that represent the top-level domain country code geodiversity as a percentage

                      of clients visiting the domain.'
                    items:
                      type: number
                      description: 'A score that represents the top-level domain country code geodiversity as a percentage

                        of clients visiting the domain. Occurs most often with domains that have a ccTLD.

                        The score is the normalized ratio between 0 and 1.'
                    example:
                    - 0.0
                  geoscore:
                    type: number
                    description: 'A score that represents how far the different physical locations serving this name

                      are from each other.'
                    example: 0
                  ks_test:
                    type: number
                    description: 'A number that represents the Kolmogorov-Smirnov test on geodiversity.

                      Zero indicates that the client traffic matches what is expected for this top-level domain.'
                    example: 0
                  attack:
                    type: string
                    description: 'The name of any known attacks associated with this domain.

                      Returns an empty string if no known threat associated with domain.'
                    example: ''
                  threat_type:
                    type: string
                    description: 'The type of the known attack, such as botnet or APT. Returns an empty string if no known

                      threat associated with domain.'
                    example: Botnet
                  found:
                    type: boolean
                    description: Specifies whether the results are available.
                    example: false
              example:
                dga_score: 38.301771886101335
                perplexity: 0.4540313302593146
                entropy: 2.5216406363433186
                securerank2: -1.3135141095601992
                pagerank: 0.0262532
                asn_score: -29.75810625887133
                prefix_score: -64.9070502788884
                rip_score: -75.64720536038982
                popularity: 25.335450495507196
                geodiversity:
                - 0.24074075
                - 0.018518519
                geodiversity_normalized:
                - 0.3761535390278368
                - 0.0005015965168831449
                tld_geodiversity:
                - 0.0
                geoscore: 0
                ks_test: 0
                attack: ''
                threat_type: ''
                found: true
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /domains/risk-score/{domain}:
    get:
      summary: Get Risk Score for Domain
      operationId: getDomainsRiskScore
      tags:
      - Security Information for a Domain
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/domainParam'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskScore'
              example:
                indicators:
                - indicator: Geo Popularity Score
                  normalized_score: 2
                  score: -3.610878169999999
                - indicator: Keyword Score
                  normalized_score: 3
                  score: 0.03586190445512534
                - indicator: Lexical
                  normalized_score: 52
                  score: 0.525
                - indicator: Popularity 1 Day
                  normalized_score: 100
                  score: 113.14
                - indicator: Popularity 30 Day
                  normalized_score: 100
                  score: 112.01
                - indicator: Popularity 7 Day
                  normalized_score: 100
                  score: 112.86
                - indicator: Popularity 90 Day
                  normalized_score: 100
                  score: 111.4
                - indicator: TLD Rank Score
                  normalized_score: 1
                  score: 0.010000315765229171
                - indicator: Block Status
                  normalized_score: 0
                  score: 0
                risk_score: 4
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
components:
  headers:
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
    Date:
      schema:
        type: string
        pattern: ^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
  responses:
    403Error:
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    500Error:
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    401Error:
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    404Error:
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    400Error:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  parameters:
    domainParam:
      name: domain
      in: path
      required: true
      description: A domain name.
      schema:
        type: string
      example: cisco.com
  schemas:
    RiskScore:
      type: object
      description: The indicators and risk score for the destination.
      properties:
        indicators:
          type: array
          items:
            type: object
            description: 'The properties that contribute to the risk score: `indicator`, `normalized_score`, and `score`.'
            properties:
              indicator:
                type: string
              normalized_score:
                type: integer
              score:
                type: number
                format: float
          description: 'A list of `indicator`, `normalized_score`, and `score` tuples. Each element is a behavioral

            or lexical feature that contributes to the calculation of the risk score.

            The values of `normalized_score` range between 0 and 100,

            while `score` is the raw outcome from the statistical algorithms.'
        risk_score:
          type: number
          format: float
          description: The risk score.
      example:
        indicators:
        - indicator: Geo Popularity Score
          normalized_score: 2
          score: -3.610878169999999
        - indicator: Keyword Score
          normalized_score: 3
          score: 0.03586190445512534
        - indicator: Lexical
          normalized_score: 52
          score: 0.525
        - indicator: Popularity 1 Day
          normalized_score: 100
          score: 113.14
        - indicator: Popularity 30 Day
          normalized_score: 100
          score: 112.01
        - indicator: Popularity 7 Day
          normalized_score: 100
          score: 112.86
        - indicator: Popularity 90 Day
          normalized_score: 100
          score: 111.4
        - indicator: TLD Rank Score
          normalized_score: 1
          score: 0.010000315765229171
        - indicator: Block Status
          normalized_score: 0
          score: 0
        risk_score: 4
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: The client credential flow.
      flows:
        clientCredentials:
          scopes:
            investigate.investigate:read: Investigate read access
            investigate.bulk:read: Investigate bulk read access
          tokenUrl: https://api.umbrella.com/auth/v2/token
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/investigate/investigate.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/investigate/investigate.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/