DomainTools Monitors API

openapi: 3.2.0
info:
  title: DomainTools Lookups Monitors API
  version: 1.0.0
  description: 'The OpenAPI spec for DomainTools Lookup, Reversing, and Monitoring endpoints.

    '
  contact:
    name: DomainTools Support
    url: https://www.domaintools.com/support
    email: enterprisesupport@domaintools.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.domaintools.com/company/terms-of-service/
servers:
- url: https://api.domaintools.com
  description: DomainTools APIs
security:
- header_auth: []
- open_key_auth: []
- hmac_auth: []
tags:
- name: Monitors
  description: 'Endpoints for monitoring new domain registrations, changes to IP ranges, and other key infrastructure events based on specific terms.

    '
paths:
  /v1/ip-monitor/:
    get:
      operationId: getIpMonitor
      summary: IP Monitor
      description: Receive notifications for new and/or deleted domains on a given IP Address.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/ipAddressQuery'
      - $ref: '#/components/parameters/daysBack'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/appPartner'
      - $ref: '#/components/parameters/appName'
      - $ref: '#/components/parameters/appVersion'
      - $ref: '#/components/parameters/responseFormat'
      responses:
        '200':
          $ref: '#/components/responses/IpMonitorSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      externalDocs:
        url: https://docs.domaintools.com/api/monitors/ip-monitor/
  /v1/mark-alert/:
    get:
      operationId: getBrandMonitor
      summary: Brand Monitor
      description: Monitor new domain registrations for specific keywords.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/monitorQuery'
      - $ref: '#/components/parameters/excludeTerms'
      - $ref: '#/components/parameters/domainStatus'
      - $ref: '#/components/parameters/daysBack'
      - $ref: '#/components/parameters/appPartner'
      - $ref: '#/components/parameters/appName'
      - $ref: '#/components/parameters/appVersion'
      - $ref: '#/components/parameters/responseFormat'
      responses:
        '200':
          $ref: '#/components/responses/BrandMonitorSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      externalDocs:
        url: https://docs.domaintools.com/api/monitors/brand-monitor/
  /v1/name-server-monitor/:
    get:
      operationId: getNameServerMonitor
      summary: Name Server Monitor
      description: Receive notification when there are new and/or deleted domains on a given Domain Name Server.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/nameServerQuery'
      - $ref: '#/components/parameters/daysBack'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/appPartner'
      - $ref: '#/components/parameters/appName'
      - $ref: '#/components/parameters/appVersion'
      - $ref: '#/components/parameters/responseFormat'
      responses:
        '200':
          $ref: '#/components/responses/NameServerMonitorSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      externalDocs:
        url: https://docs.domaintools.com/api/monitors/name-server-monitor/
  /v1/registrant-alert/:
    get:
      operationId: getRegistrantMonitor
      summary: Registrant Monitor
      description: Receive notification when specific people or organizations register, renew, or delete domain names.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/monitorQuery'
      - $ref: '#/components/parameters/excludeTerms'
      - $ref: '#/components/parameters/daysBack'
      - $ref: '#/components/parameters/resultsLimit'
      - $ref: '#/components/parameters/appPartner'
      - $ref: '#/components/parameters/appName'
      - $ref: '#/components/parameters/appVersion'
      - $ref: '#/components/parameters/responseFormat'
      responses:
        '200':
          $ref: '#/components/responses/RegistrantMonitorSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      externalDocs:
        url: https://docs.domaintools.com/api/monitors/registrant-monitor/
components:
  parameters:
    nameServerQuery:
      in: query
      name: query
      description: The name server hostname to query.
      required: true
      schema:
        $ref: '#/components/schemas/Hostname'
    page:
      in: query
      name: page
      description: Sets the page of results to retrieve from the server (used in services that support pagination).
      schema:
        type: integer
        minimum: 1
    ipAddressQuery:
      in: query
      name: query
      description: The IP Address to query.
      required: true
      schema:
        $ref: '#/components/schemas/IPv4Address'
    excludeTerms:
      in: query
      name: exclude
      description: 'Domain names with these words will be excluded from the result set. For exclusions of multiple terms, use the `|` character as a separator.

        '
      schema:
        $ref: '#/components/schemas/BasicString'
    responseFormat:
      name: format
      in: query
      description: 'Specifies the desired response format.

        '
      schema:
        $ref: '#/components/schemas/ResponseFormat'
    domainStatus:
      in: query
      name: domain_status
      description: 'Sets the scope of domain names to search. Defaults to searching both `new` and `on-hold` domains.

        '
      schema:
        type: string
        enum:
        - new
        - on-hold
    appPartner:
      name: app_partner
      in: query
      description: 'Your product name.

        '
      schema:
        $ref: '#/components/schemas/IdentifierString'
    monitorQuery:
      in: query
      name: query
      description: 'One or more terms, where the pipe character ( | ) may be used as a logical AND to require that all strings be present in order to match.

        '
      required: true
      schema:
        $ref: '#/components/schemas/BasicString'
    appVersion:
      name: app_version
      in: query
      description: 'Version of your integration/connector.

        '
      schema:
        $ref: '#/components/schemas/IdentifierString'
    appName:
      name: app_name
      in: query
      description: 'Appliance, module, or playbook, or any combination of these.

        '
      schema:
        $ref: '#/components/schemas/IdentifierString'
    resultsLimit:
      name: limit
      in: query
      description: 'Specify the maximum number of records to retrieve in an API query.

        The maximum value is **100**.

        '
      schema:
        type: integer
        maximum: 100
        minimum: 1
    daysBack:
      in: query
      name: days_back
      description: Search domains registered up to six days prior to the current date.
      schema:
        type: integer
        minimum: 1
        maximum: 6
  schemas:
    IdentifierString:
      type: string
      minLength: 1
      maxLength: 128
      description: A short identifier, code, or handle.
    IpMonitor:
      type: object
      description: Response for the IP Monitor endpoint.
      properties:
        response:
          type: object
          properties:
            limit:
              type: integer
            date:
              type: string
            ip_address:
              type: string
            total:
              type: string
            page:
              type: integer
            page_count:
              type: integer
            alerts:
              type: array
              items:
                type: object
                properties:
                  previous_ip_address:
                    type: string
                  new_ip_address:
                    type: string
                  action:
                    type: string
                  domain:
                    type: string
    HtmlResponse:
      type: string
      description: 'HTML-formatted response body. JSON is the primary documented format; HTML response schemas are not individually documented.

        '
    Hostname:
      type: string
      format: hostname
      description: A valid, fully-qualified domain name (FQDN).
    BasicString:
      type: string
      minLength: 1
      maxLength: 255
      description: A non-empty string with a standard length limit.
    XmlResponse:
      type: string
      description: 'XML-formatted response body. JSON is the primary documented format; XML response schemas are not individually documented.

        '
    IPv4Address:
      type: string
      format: ipv4
      description: A standard IPv4 address.
    BrandMonitor:
      type: object
      description: Response for the Brand Monitor endpoint.
      properties:
        response:
          type: object
          properties:
            query:
              type: string
            exclude:
              type: string
            new:
              type: boolean
            on-hold:
              type: boolean
            date:
              type: string
            total:
              type: integer
            alerts:
              type: array
              items:
                type: object
                properties:
                  domain:
                    type: string
                  status:
                    type: string
    RegistrantMonitor:
      type: object
      description: Response for the Registrant Monitor endpoint.
      properties:
        response:
          type: object
          properties:
            query:
              type: string
            limit:
              type: number
            total:
              type: number
            date:
              type: string
            alerts:
              type: array
              items:
                type: object
                properties:
                  domain:
                    type: string
                  match_type:
                    type: string
                  current_owner:
                    type: string
                  created:
                    type: string
                  modified:
                    type: string
                  last_owner:
                    type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: An internal error code.
            message:
              type: string
              description: A human-readable error message.
        resources:
          type: object
          description: Links to support or documentation resources.
          properties:
            support:
              type: string
              description: URL to API documentation or support.
    NameServerMonitor:
      type: object
      description: Response for the Name Server Monitor endpoint.
      properties:
        response:
          type: object
          properties:
            limit:
              type: integer
            date:
              type: string
            name_server:
              type: string
            total:
              type: integer
            page:
              type: integer
            page_count:
              type: integer
            alerts:
              type: array
              items:
                type: object
                properties:
                  new_name_server:
                    type: string
                  old_name_server:
                    type: string
                  action:
                    type: string
                  domain:
                    type: string
    ResponseFormat:
      type: string
      enum:
      - html
      - json
      - xml
      description: 'The desired response format.

        '
  responses:
    Forbidden:
      description: '403: Forbidden. The API credentials provided do not have access to the requested resource or endpoint.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NameServerMonitorSuccess:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NameServerMonitor'
        application/xml:
          schema:
            $ref: '#/components/schemas/XmlResponse'
        text/html:
          schema:
            $ref: '#/components/schemas/HtmlResponse'
    NotFound:
      description: '404: Not Found. The requested resource does not exist.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RegistrantMonitorSuccess:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrantMonitor'
        application/xml:
          schema:
            $ref: '#/components/schemas/XmlResponse'
        text/html:
          schema:
            $ref: '#/components/schemas/HtmlResponse'
    IpMonitorSuccess:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IpMonitor'
        application/xml:
          schema:
            $ref: '#/components/schemas/XmlResponse'
        text/html:
          schema:
            $ref: '#/components/schemas/HtmlResponse'
    BadRequest:
      description: '400: Bad Request. The request was invalid. The response will contain details about the error.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BrandMonitorSuccess:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BrandMonitor'
        application/xml:
          schema:
            $ref: '#/components/schemas/XmlResponse'
        text/html:
          schema:
            $ref: '#/components/schemas/HtmlResponse'
    ServiceUnavailable:
      description: '503: Service Unavailable. The service is temporarily unavailable.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: '401: Unauthorized. API credentials are required and were not provided, or the provided credentials are not valid.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: '500: Internal Server Error. An unexpected error occurred on the server. If the problem persists, contact DomainTools support.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    header_auth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'A secure authentication method where the API key is provided in the `X-Api-Key` HTTP request header.

        '
    open_key_auth:
      type: http
      scheme: basic
      description: 'A simple authentication scheme using your `api_username` as the username and your `api_key` as the password. We strongly recommend using HMAC or Header authentication instead to avoid exposing your credentials.

        '
    hmac_auth:
      type: apiKey
      in: query
      name: signature
      description: 'A secure scheme using a Hashed Message Authentication Code (HMAC).

        This method requires three query parameters to be sent with the request:

        1. `api_username`: Your API username.

        2. `timestamp`: The current timestamp in ISO 8601 format (e.g., `2020-02-01T22:37:59Z`).

        3. `signature`: The HMAC signature of the request. This is a hash (SHA-256 recommended) of your username, the timestamp, and the request URI, signed with your secret API key.

        '