openapi: 3.2.0
info:
  title: dnssec.public_api DNS Security API API
  version: Beta
  description: DNS Security API
servers:
- url: https://api.dns.service.paloaltonetworks.com
tags:
- description: DNS Security API
  name: DNS Security API
paths:
  /v1/domain/changerequest:
    post:
      description: A POST request to submit change requests for domains with their new categories. Batch limit is 20 entries per request with a maximum of 10 request submissions per 24 hour period (for a total of 200 individual domain change requests).
      operationId: PublicApi_V1DomainChangeRequest
      responses:
        '200':
          description: 200 Ok
          headers:
            X-Quota-Limit-Remaining:
              description: The remaining number of quota in this window (per day). When it drops to 0, return HTTP StatusCode = 429
              schema:
                type: integer
            X-Quota-Limit-Reset:
              description: The unix timestamp at which the current quota window resets. Quota is refreshed every day.
              schema:
                type: integer
            X-Quota-Limit-Total:
              description: Total number of quota in this window (per day).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: error message content...
                success: false
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Unauthorized
                success: false
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Forbidden
                success: false
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Not Found
                success: false
        '415':
          description: 415 Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Unsupported Media Type
                success: false
        '429':
          description: 429 Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Too Many Requests
                success: false
        '500':
          description: 500 Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: error message...
                success: false
      security:
      - X-DNS-API-APIKEY: []
      summary: Request Domain Category Change.
      tags:
      - DNS Security API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/public_apiV1DomainBulkChangeRequest'
        required: true
  /v1/domain/info:
    post:
      description: "A POST request to retrieve general information about the specified domains, including WHOIS information, PassiveDNS, DNS Security / PAN-DB category, and the DGA score. \n>⚠️ ***Batch limit is 20 entries***\n"
      operationId: PublicApi_V1DomainInfo
      responses:
        '200':
          description: 200 Ok
          headers:
            X-Quota-Limit-Remaining:
              description: The remaining number of quota in this window (per day). When it drops to 0, return HTTP StatusCode = 429
              schema:
                type: integer
            X-Quota-Limit-Reset:
              description: The unix timestamp at which the current quota window resets. Quota is refreshed every day.
              schema:
                type: integer
            X-Quota-Limit-Total:
              description: Total number of quota in this window (per day).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiV1DomainInfoResponse'
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: error message content...
                success: false
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Unauthorized
                success: false
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Forbidden
                success: false
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Not Found
                success: false
        '415':
          description: 415 Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Unsupported Media Type
                success: false
        '429':
          description: 429 Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: Too Many Requests
                success: false
        '500':
          description: 500 Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_apiGeneralResponse'
              example:
                message: error message...
                success: false
      security:
      - X-DNS-API-APIKEY: []
      summary: Request Domain Information.
      tags:
      - DNS Security API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/public_apiV1DomainInfoRequest'
        required: true
components:
  schemas:
    public_apiCategoryHistory:
      properties:
        category:
          description: The history category from PanDB
          type: string
        evidences:
          description: A list of evidences supporting the category.
          items:
            type: string
          type: array
        time:
          description: The time when the category is published.
          type: string
      type: object
    public_apiV1DomainChangeRequest:
      properties:
        comment:
          description: Comment for change request review process.
          type: string
        domain:
          description: The domain name
          maxLength: 253
          type: string
        suggestedCategory:
          description: Suggested new category for domain name. You must use one of the valid categories shown above.
          enum:
          - malware
          - command-and-control
          - phishing
          - dynamic-dns
          - grayware
          - parked
          - proxy-avoidance-and-anonymizers
          - benign
          type: string
      type: object
    public_apiV1DomainInfoResult:
      properties:
        category:
          description: Domain category from DNS and PanDB.
          type: string
        categoryHistories:
          description: A list of history category information from PanDB.
          items:
            $ref: '#/components/schemas/public_apiCategoryHistory'
          type: array
        dgaScore:
          description: The score of DGA domain.
          format: double
          type: number
        domain:
          description: The domain name queried.
          type: string
        ipHistories:
          description: A list of history DNS records of the domain from PassiveDNS.
          items:
            $ref: '#/components/schemas/public_apiIpHistory'
          type: array
        whoisRecords:
          description: A list of records of the domain from Whois.
          items:
            $ref: '#/components/schemas/public_apiWhoisRecord'
          type: array
      type: object
    public_apiIpHistoryGeo:
      properties:
        countryCode:
          type: string
          description: Country code associated with the IP.
        countryName:
          type: string
          description: Country name associated with the IP.
      type: object
    public_apiIpHistory:
      properties:
        asn:
          $ref: '#/components/schemas/public_apiIpHistoryAsn'
        count:
          description: The number of DNS records that we had seen was resolving the given domain in PassiveDNS.
          format: uint64
          type: string
        first:
          description: The first seen date time of the DNS record. UTC datetime in "YYYY-mm-dd HH:mm:ss" format.
          type: string
        geo:
          $ref: '#/components/schemas/public_apiIpHistoryGeo'
        ip:
          description: DNS record. IPv4 or IPv6.
          type: string
        last:
          description: The last seen date time of the DNS record. UTC datetime in "YYYY-mm-dd HH:mm:ss" format.
          type: string
        type:
          description: Type of the DNS record. We only support A(IPv4) and AAAA(IPv6) type.
          type: string
      type: object
    public_apiV1DomainInfoDomains:
      example:
        domain: onion.top
      properties:
        domain:
          description: The domain name you want to query
          maxLength: 253
          type: string
      required:
      - domain
      title: /v1/domain/info
      type: object
    public_apiWhoisRecord:
      properties:
        Audit_auditUpdatedDate:
          title: "string RegistryData_rawText = 13 [json_name = \"RegistryData_rawText\"]; // remove this in the return to customer\n string WhoisRecord_rawText = 14 [json_name = \"WhoisRecord_rawText\"]; // remove this in the return to customer"
          type: string
        administrativeContact_city:
          type: string
        administrativeContact_country:
          type: string
        administrativeContact_email:
          title: string administrativeContact_rawText = 27 [json_name = "administrativeContact_rawText"];
          type: string
        administrativeContact_fax:
          type: string
        administrativeContact_name:
          type: string
        administrativeContact_organization:
          type: string
        administrativeContact_postalCode:
          type: string
        administrativeContact_state:
          type: string
        administrativeContact_telephone:
          type: string
        contactEmail:
          type: string
        createdDate:
          type: string
        domainName:
          type: string
        expiresDate:
          type: string
        nameServers:
          type: string
        registrant_city:
          type: string
        registrant_country:
          type: string
        registrant_email:
          title: string registrant_rawText = 16 [json_name = "registrant_rawText"];
          type: string
        registrant_fax:
          type: string
        registrant_name:
          type: string
        registrant_organization:
          type: string
        registrant_postalCode:
          type: string
        registrant_state:
          type: string
        registrant_street1:
          type: string
        registrant_telephone:
          type: string
        registrarIANAID:
          type: string
        registrarName:
          type: string
        standardRegCreatedDate:
          type: string
        standardRegExpiresDate:
          type: string
        standardRegUpdatedDate:
          type: string
        status:
          type: string
        technicalContact_city:
          type: string
        technicalContact_country:
          type: string
        technicalContact_email:
          title: string technicalContact_rawText = 37 [json_name = "technicalContact_rawText"];
          type: string
        technicalContact_fax:
          type: string
        technicalContact_name:
          type: string
        technicalContact_organization:
          type: string
        technicalContact_postalCode:
          type: string
        technicalContact_state:
          type: string
        technicalContact_telephone:
          type: string
        updatedDate:
          type: string
        whoisServer:
          type: string
      type: object
    public_apiV1DomainBulkChangeRequest:
      example:
        changeRequests:
        - domain: portal.dynect.net
          suggestedCategory: malware
          comment: Domain triggered AV software.
        - domain: azr-iad1.rum.dynapis.com
          suggestedCategory: malware
          comment: Incorrectly categorized.
        email: dnssecurity@paloaltonetworks.com
        test: false
      properties:
        changeRequests:
          description: Provide a list of domain change request with domains, categories, comments.
          items:
            $ref: '#/components/schemas/public_apiV1DomainChangeRequest'
          type: array
        email:
          description: Provide an email to receive results of change requests. If none provided, email will assume value associated with DNS Security API key.
          type: string
        test:
          default: false
          description: When set to true, this bulk change request will be acknowledged by API, but not forwarded for review
          pattern: true | false
          type: boolean
      required:
      - changeRequests
      type: object
    public_apiV1DomainInfoRequest:
      example:
        domains:
        - domain: onion.top
        - domain: top.onion
        end: '2022-07-01'
        start: '2022-01-01'
      properties:
        domains:
          description: Provides a list of domain object details by matching it with the information contained in the DNS Security cloud database.
          items:
            $ref: '#/components/schemas/public_apiV1DomainInfoDomains'
          maxItems: 20
          type: array
        end:
          description: "A user-specified end date of PassiveDNS records. UTC date in YYYY-mm-dd format, start cannot be later than End. Defaults to 6 months after start date if provided, otherwise current date. \n>⚠️ ***Passive DNS records are displayed under the IP Histories entry in the output.***\n"
          pattern: YYYY-mm-dd
          type: string
        start:
          description: "A user-specified start date of PassiveDNS records. UTC date in YYYY-mm-dd format, start cannot be later than end. Defaults to 6 months before end date if provided, otherwise 6 months before current date. \n>⚠️ ***Passive DNS records are displayed under the IP Histories entry in the output.***\n"
          pattern: YYYY-mm-dd
          type: string
      required:
      - domains
      type: object
    public_apiIpHistoryAsn:
      properties:
        ASName:
          type: string
          description: The Autonomous System Name of the IP
        ASNumber:
          format: int64
          type: string
          description: The Autonomous System Number of the IP
      type: object
    public_apiV1DomainInfoResponse:
      example:
        message: ''
        results:
        - category: command-and-control
          categoryHistories:
          - category: command-and-control
            evidences: []
            time: '2019-03-20T16:49:33Z'
          domain: test-c2.testpanw.com
          ipHistories:
          - asn:
              ASName: Not routed, None
              ASNumber: 0
            count: 7
            first: '2022-06-29T17:34:09Z'
            geo:
              countryCode: AU
              countryName: Australia
            ip: 1.2.3.4
            last: '2022-06-29T17:38:49Z'
            type: array
          whoisRecords:
          - Audit_auditUpdatedDate: 2020-03-19 00:00:00 UTC
            administrativeContact_city: Scottsdale
            administrativeContact_country: UNITED STATES
            administrativeContact_email: testpanw.com@domainsbyproxy.com
            administrativeContact_fax: '14806242598'
            administrativeContact_name: Registration Private
            administrativeContact_organization: Domains By Proxy, LLC
            administrativeContact_postalCode: '85260'
            administrativeContact_state: Arizona
            administrativeContact_telephone: '14806242599'
            contactEmail: testpanw.com@domainsbyproxy.com
            createdDate: '2019-02-19T20:32:00Z'
            domainName: testpanw.com
            expiresDate: '2021-02-19T20:32:00Z'
            nameServers: NS1.PANWSINKHOLE.COM|NS2.PANWSINKHOLE.COM|
            registrant_city: Scottsdale
            registrant_country: UNITED STATES
            registrant_email: testpanw.com@domainsbyproxy.com
            registrant_fax: '14806242598'
            registrant_name: Registration Private
            registrant_organization: Domains By Proxy, LLC
            registrant_postalCode: '85260'
            registrant_state: Arizona
            registrant_street1: DomainsByProxy.com|14455 N. Hayden Road
            registrant_telephone: '14806242599'
            registrarIANAID: '146'
            registrarName: GoDaddy.com, LLC
            standardRegCreatedDate: 2019-02-19 20:32:00 UTC
            standardRegExpiresDate: 2021-02-19 20:32:00 UTC
            standardRegUpdatedDate: 2019-07-03 10:34:48 UTC
            status: clientDeleteProhibited clientRenewProhibited clientTransferProhibited clientUpdateProhibited
            technicalContact_city: Scottsdale
            technicalContact_country: UNITED STATES
            technicalContact_email: testpanw.com@domainsbyproxy.com
            technicalContact_fax: '14806242598'
            technicalContact_name: Registration Private
            technicalContact_organization: Domains By Proxy, LLC
            technicalContact_postalCode: '85260'
            technicalContact_state: Arizona
            technicalContact_telephone: '14806242599'
            updatedDate: '2019-07-03T10:34:48Z'
            whoisServer: whois.godaddy.com
        success: true
      properties:
        message:
          description: If "success" is true, the message should be empty.
          type: string
        results:
          description: The list of result object.
          items:
            $ref: '#/components/schemas/public_apiV1DomainInfoResult'
          type: array
        success:
          type: boolean
      type: object
    public_apiGeneralResponse:
      example:
        message: Change request has been successfully submitted.
        success: true
      properties:
        message:
          type: string
        success:
          type: boolean
      title: GeneralResponse is used for reply when error happens and response for change request submittion
      type: object
  securitySchemes:
    X-DNS-API-APIKEY:
      description: API key to query https://api.dns.service.paloaltonetworks.com
      in: header
      name: X-DNS-API-APIKEY
      type: apiKey