openapi: 3.0.3
servers:
  - url: "https://api.domaintools.com"
    description: DomainTools APIs
info:
  title: Real-Time Threat Intelligence Feeds
  version: 0.0.4
  description: |
    Real-Time Threat Intelligence Feeds provide data on the different stages of the domain lifecycle: from first-observed in the wild, to newly re-activated after a period of quiet. Access current feed data in real-time or retrieve historical feed data through separate APIs.

    The **Real-time Feed API** returns results based on absolute or relative times, and is documented here. The **Download API** returns archives of past results as signed, temporary AWS S3 file links. Some feeds are also available for DNS firewalls as [Response Policy Zone](https://docs.domaintools.com/feeds/realtime/userguide/#rpz) files, a feature which is not supported by the OpenAPI specification.

    Consult our [technical documentation](https://docs.domaintools.com/feeds/realtime/) for more information.
security:
  - ApiKeyAuth: []

tags:
  - name: Domain Discovery Feed
    description: New apex domains (e.g. `example.com` but not `www.example.com`) emitted as soon as they are first observed in domain registration information, by our global sensor network, or reported by trusted third parties.
  - name: Domain Hotlist Feed
    description: High-risk apex domains with activity detected within the past 24 hours by DomainTools' global sensor network. Includes real-time spam, phishing, malware, and overall risk scores.
  - name: Domain Risk Feed
    description: High-risk apex domains emitted when their risk scores change, including domains that appear dormant. Includes real-time spam, phishing, malware, and overall risk scores.
  - name: Newly Active Domains Feed
    description: Domains observed for the first time, or after a period of 10 or more days of inactivity, by DomainTools' global sensor network.
  - name: Newly Observed Domains Feed
    description: Domains observed for the first time by DomainTools' global sensor network.
  - name: Newly Observed Hostnames Feed
    description: Hostname resolutions observed for the first time by DomainTools' global sensor network.
  - name: Parsed Domain RDAP Feed
    description: Changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP). Compliments the 5-Minute WHOIS Feed.
  - name: Download API
    description: Returns archives of past results as signed, temporary AWS S3 file links.
paths:
  '/v1/download/{feed}/':
    get:
      operationId: getDownload
      summary: Get signed URLs for a feed file or set of files
      tags:
        - Download API
      description: Access to our Daily Threat Intelligence Feeds is provided through our Download API.
      parameters:
        - name: feed
          in: path
          required: true
          schema:
            type: string
            enum:
              - domaindiscovery
              - domainhotlist
              - domainrdap
              - domainrisk
              - nad
              - nod
              - noh
        - $ref: '#/components/parameters/app_partner'
        - $ref: '#/components/parameters/app_name'
        - $ref: '#/components/parameters/app_version'
      responses:
        '200':
          $ref: '#/components/responses/200ResponseDownload'
        '400':
          description: Bad Request. The request could not be understood or was missing required parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                  resources:
                    type: object
                    properties:
                      support:
                        type: string
                        format: uri
        '403':
          description: Forbidden. Authentication credentials were missing or incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                  resources:
                    type: object
                    properties:
                      support:
                        type: string
                        format: uri
      externalDocs:
        url: 'https://docs.domaintools.com/feeds/'
  /v1/feed/domaindiscovery/:
    get:
      summary: Returns data from the Real-Time Domain Discovery feed.
      tags:
        - Domain Discovery Feed
      parameters:
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/top"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseStandard"
        "206":
          $ref: "#/components/responses/206ResponseStandard"
        "401":
          $ref: "#/components/responses/ErrorResponseStandard"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Domain Discovery Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseStandard"
        "401":
          $ref: "#/components/responses/ErrorResponseStandard"
        "404":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
  /v1/feed/domainhotlist/:
    get:
      summary: Returns data from the Real-Time Domain Hotlist Feed.
      tags:
        - Domain Hotlist Feed
      parameters:
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/phishing_min"
        - $ref: "#/components/parameters/malware_min"
        - $ref: "#/components/parameters/spam_min"
        - $ref: "#/components/parameters/proximity_min"
        - $ref: "#/components/parameters/overall_min"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseDomainRisk"
        "206":
          $ref: "#/components/responses/206ResponseDomainRisk"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Domain Hotlist Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/404ResponseSessionID"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
  /v1/feed/domainrdap/:
    get:
      summary: Returns data from the Domain RDAP feed.
      tags:
        - Parsed Domain RDAP Feed
      parameters:
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/top"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseDRDAP"
        "206":
          $ref: "#/components/responses/206ResponseDRDAP"
        "401":
          description: Unauthorized
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Parsed Domain RDAP Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/404ResponseSessionID"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"

  /v1/feed/domainrisk/:
    get:
      summary: Returns data from the Real-Time Domain Risk feed.
      tags:
        - Domain Risk Feed
      parameters:
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/phishing_min"
        - $ref: "#/components/parameters/malware_min"
        - $ref: "#/components/parameters/spam_min"
        - $ref: "#/components/parameters/proximity_min"
        - $ref: "#/components/parameters/overall_min"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseDomainRisk"
        "206":
          $ref: "#/components/responses/206ResponseDomainRisk"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Domain Risk Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/404ResponseSessionID"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
  /v1/feed/nad/:
    get:
      summary: Returns data from the Newly Active Domains feed.
      tags:
        - Newly Active Domains Feed
      parameters:
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/top"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseStandard"
        "206":
          $ref: "#/components/responses/206ResponseStandard"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Newly Active Domains Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/404ResponseSessionID"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
  /v1/feed/nod/:
    get:
      summary: Returns data from the Newly Observed Domains feed.
      tags:
        - Newly Observed Domains Feed
      parameters:
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/top"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseStandard"
        "206":
          $ref: "#/components/responses/206ResponseStandard"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Newly Observed Domains Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/404ResponseSessionID"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
  /v1/feed/noh/:
    get:
      summary: Returns data from the Newly Observed Hosts feed.
      tags:
        - Newly Observed Hostnames Feed
      parameters:
        - $ref: "#/components/parameters/domain"
        - $ref: "#/components/parameters/before"
        - $ref: "#/components/parameters/after"
        - $ref: "#/components/parameters/headers"
        - $ref: "#/components/parameters/sessionID"
        - $ref: "#/components/parameters/fromBeginning"
        - $ref: "#/components/parameters/top"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseStandard"
        "206":
          $ref: "#/components/responses/206ResponseStandard"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "406":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
    delete:
      summary: Delete a sessionID
      tags:
        - Newly Observed Hostnames Feed
      parameters:
        - $ref: "#/components/parameters/sessionID"
      responses:
        "200":
          $ref: "#/components/responses/200ResponseSimple"
        "401":
          $ref: "#/components/responses/401ResponseSimple"
        "404":
          $ref: "#/components/responses/ErrorResponseStandard"
        "422":
          $ref: "#/components/responses/ErrorResponseStandard"
components:
  parameters:
    domain:
      name: domain
      in: query
      description: Filter for an exact domain or a substring contained within a domain by prefixing or suffixing your substring with "*". Check the documentation for examples.
      required: false
      schema:
        $ref: "#/components/schemas/DomainFilter"
    before:
      name: before
      in: query
      description: Filter for records before the given time value inclusive or time offset relative to now
      required: false
      schema:
        $ref: "#/components/schemas/TimeFilter"
    after:
      name: after
      in: query
      description: Filter for records after the given time value inclusive or time offset relative to now
      required: false
      schema:
        $ref: "#/components/schemas/TimeFilter"
    headers:
      name: headers
      in: query
      description: "Use in combination with Accept: text/csv headers to control if headers are sent or not"
      required: false
      schema:
        $ref: "#/components/schemas/Headers"
    fromBeginning:
      name: fromBeginning
      in: query
      description: Only allowed for new sessionIDs, start the session from the oldest data available
      required: false
      schema:
        type: boolean
    sessionID:
      name: sessionID
      in: query
      description: A custom string to distinguish between different sessions
      required: false
      schema:
        $ref: "#/components/schemas/SessionID"
# Risk Score
    malware_min:
      name: malware_min
      in: query
      description: Filter for domains with malware risk scores greater than or equal to this value
      required: false
      schema:
        $ref: "#/components/schemas/Score"
    spam_min:
      name: spam_min
      in: query
      description: Filter for domains with spam risk scores greater than or equal to this value
      required: false
      schema:
        $ref: "#/components/schemas/Score"
    proximity_min:
      name: proximity_min
      in: query
      description: Filter for domains with proximity risk scores greater than or equal to this value
      required: false
      schema:
        $ref: "#/components/schemas/Score"
    overall_min:
      name: overall_min
      in: query
      description: Filter for domains with overall risk scores greater than or equal to this value. Note that the lowest overall risk score is 70.
      required: false
      schema:
        $ref: "#/components/schemas/Score"
    phishing_min:
      name: phishing_min
      in: query
      description: Filter for domains with phishing risk scores greater than or equal to this value
      required: false
      schema:
        $ref: "#/components/schemas/Score"
    top:
      name: top
      in: query
      description: Limit the number of results to the top N, where N is the value of this parameter.
      required: false
      schema:
        $ref: "#/components/schemas/Top"
    app_name:
      in: query
      name: app_name
      description: 'Appliance, module, or playbook, or any combination of these'
      schema:
        type: string
        default: DomainTools_APIs
    app_partner:
      in: query
      name: app_partner
      description: Your product name
      schema:
        type: string
        default: SwaggerHub
    app_version:
      in: query
      name: app_version
      description: Version of your integration/connector
      schema:
        type: number
        default: 1.4
        multipleOf: 0.1
  schemas:
    DomainFilter:
      type: string
      description: Domain character set restricted by the DNS specification LDH. International characters should be specified in punycode. A trailing dot is acceptable.
    TimeFilter:
      type: string
      description: Check the documentation for allowed formats and examples.
    Headers:
      type: boolean
    SessionID:
      type: string
      minLength: 1
      maxLength: 64
      pattern: "[a-zA-Z0-9-]+"
    Score:
      type: integer
      minimum: 0
      maximum: 100
    Top:
      type: integer
      minimum: 0
      maximum: 1000000000
  responses:
    200ResponseDomainRisk:
      description: OK
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              domain:
                description: The domain without the trailing dot
                type: string
              phishing_risk:
                $ref: "#/components/schemas/Score"
              malware_risk:
                $ref: "#/components/schemas/Score"
              spam_risk:
                $ref: "#/components/schemas/Score"
              proximity_risk:
                $ref: "#/components/schemas/Score"
              overall_risk:
                $ref: "#/components/schemas/Score"
            example: '{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}'
        text/csv:
          schema:
            type: string
            example: badactor.com,75,85,88,99,99
    200ResponseDownload:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              response:
                type: object
                properties:
                  download_name:
                    description: The feed (scope) of the download.
                    type: string
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          description: A feed directory containing a feed file
                          type: string
                        last_modified:
                          description: Last modified date of the file in ISO 8601 format.
                          type: string
                        etag:
                          description: Entity tag (a hash of the object).
                          type: string
                        size:
                          description: Size in kilobytes (KB) or bytes
                          type: string
                        url:
                          description: Signed AWS CloudFront download URL
                          type: string
    200ResponseDRDAP:
      description: OK
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              timestamp:
                description: The observation timestamp
                type: string
              domain:
                description: The newly observed domain without the trailing dot
                type: string
              raw_record:
                description: raw record
                type: object
                properties: {}
              parsed_record:
                description: parsed record
                type: object
                properties: {}
            example: '{"timestamp": "2012-10-03T16:03:12Z", "domain": "badactor.com", "raw_record": {}, "parsed_record": {}}'
    200ResponseStandard:
      description: OK
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              timestamp:
                description: The observation timestamp
                type: string
              domain:
                description: The emitted Domain Name without the trailing dot
                type: string
            example: '{"timestamp": "2012-10-03T16:03:12Z", "domain": "www.badactor.com"}'
        text/csv:
          schema:
            type: string
            example: 2012-10-03T16:03:12Z,www.badactor.com
    200ResponseSimple:
      description: OK
    206ResponseDomainRisk:
      description: Partial content limited to 10M rows or 1 hour evaluation window
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              domain:
                description: The domain without the trailing dot
                type: string
              phishing_risk:
                $ref: "#/components/schemas/Score"
              malware_risk:
                $ref: "#/components/schemas/Score"
              spam_risk:
                $ref: "#/components/schemas/Score"
              proximity_risk:
                $ref: "#/components/schemas/Score"
              overall_risk:
                $ref: "#/components/schemas/Score"
            example: '{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}'
        text/csv:
          schema:
            type: string
            example: badactor.com,75,85,88,99,99
    206ResponseDRDAP:
      description: Partial content limited to 10M rows or 1 hour evaluation window
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              timestamp:
                description: The observation timestamp
                type: string
              domain:
                description: The newly observed domain without the trailing dot
                type: string
              raw_record:
                description: raw_record
                type: object
                properties: {}
              parsed_record:
                description: parsed_record
                type: object
                properties: {}
            example: '{"timestamp": "2012-10-03T16:03:12Z", "domain": "badactor.com", "raw_record": {}, "parsed_record": {}}'
    206ResponseStandard:
      description: Partial content limited to 10M rows or 1 hour evaluation window
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              timestamp:
                description: The observation timestamp
                type: string
              domain:
                description: The emitted Domain Name without the trailing dot
                type: string
            example: '{"timestamp": "2012-10-03T16:03:12Z", "domain": "www.badactor.com"}'
        text/csv:
          schema:
            type: string
            example: 2012-10-03T16:03:12Z,www.badactor.com
    401ResponseSimple:
      description: Unauthorized
    404ResponseSessionID:
      description: SessionID not found.
    ErrorResponseStandard:
      description: Error Message
      content:
        application/x-ndjson:
          schema:
            type: object
            properties:
              error:
                description: An error message
                type: string
            example: '{"error": "foo is an invalid value for the headers query parameter"}'
        text/csv:
          schema:
            type: string
            example: foo is an invalid value for the headers query parameter
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Header-based authentication with the API key provided by DomainTools.