DNS Security API

openapi: 3.1.0
info:
  title: Palo Alto Networks DNS Security API
  description: >-
    REST API for querying DNS domain categorization and threat intelligence
    from Palo Alto Networks DNS Security cloud service. Beta release. Provides
    domain category lookups, risk level assessments, DNS security category
    verdicts, and network access statistics. Enables security teams to
    investigate suspicious domains, enrich security events with DNS threat
    intelligence, and automate domain-based threat hunting workflows. Requires
    an active DNS Security subscription.
  version: '1.0-beta'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.dns.service.paloaltonetworks.com/v1
  description: DNS Security API production server.
security:
- dnsApiKey: []
tags:
- name: Domains
  description: Domain categorization and threat intelligence lookups.
- name: Statistics
  description: Network access and DNS query statistics.
paths:
  /domain:
    get:
      operationId: getDomain
      summary: Palo Alto Networks Query Domain Details
      description: >-
        Returns categorization, risk level, and DNS security verdict for a
        specific domain. The response includes the URL filtering category,
        risk level score, and the DNS Security category classification used
        to make enforcement decisions. Requires a valid customer ID associated
        with an active DNS Security subscription.
      tags:
      - Domains
      parameters:
      - name: domain
        in: query
        required: true
        description: Fully qualified domain name to query (e.g., example.com).
        schema:
          type: string
        example: login.test-corp.net
      - name: customerid
        in: query
        required: true
        description: >-
          Customer ID associated with the DNS Security subscription. Used
          to scope results to the tenant's DNS Security policy context.
        schema:
          type: string
        example: '811244'
      responses:
        '200':
          description: Domain details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainDetail'
              examples:
                GetDomain200Example:
                  summary: Default getDomain 200 response
                  x-microcks-default: true
                  value:
                    domain: api.example.com
                    category: advanced
                    risk_level: low
                    risk_score: 5.81
                    dns_security_category: grayware
                    first_seen: '2024-11-07T03:24:36Z'
                    last_seen: '2025-11-18T02:10:07Z'
                    registrar: example-registrar
                    registration_date: '2026-04-16'
                    ip_addresses: &id001
                    - 10.176.161.210
                    - 10.152.189.212
        '400':
          description: Invalid domain format or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomain400Example:
                  summary: Default getDomain 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '401':
          description: Invalid or missing X-DNS-API-APIKEY header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomain401Example:
                  summary: Default getDomain 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '403':
          description: DNS Security subscription not active for the customer ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomain403Example:
                  summary: Default getDomain 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '404':
          description: Domain not found in DNS Security database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomain404Example:
                  summary: Default getDomain 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomain500Example:
                  summary: Default getDomain 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /domain/bulk:
    get:
      operationId: getDomainBulk
      summary: Palo Alto Networks Bulk Domain Query
      description: >-
        Returns categorization, risk level, and DNS security verdicts for
        multiple domains in a single request. More efficient than issuing
        individual domain queries when enriching security events that reference
        multiple domains. The domains parameter accepts a comma-separated list
        or multiple query parameter instances.
      tags:
      - Domains
      parameters:
      - name: domains
        in: query
        required: true
        description: >-
          Array of fully qualified domain names to query. Provide multiple
          values using repeated query parameters or a comma-separated list.
        schema:
          type: array
          items:
            type: string
          maxItems: 100
        style: form
        explode: true
        example:
        - example-domains_item
        - example-domains_item
      - name: customerid
        in: query
        required: true
        description: Customer ID associated with the DNS Security subscription.
        schema:
          type: string
        example: '721444'
      responses:
        '200':
          description: Bulk domain results returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Number of domains in the response.
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DomainDetail'
              examples:
                GetDomainBulk200Example:
                  summary: Default getDomainBulk 200 response
                  x-microcks-default: true
                  value:
                    total: 506
                    results:
                    - domain: api.example.com
                      category: advanced
                      risk_level: low
                      risk_score: 5.81
                      dns_security_category: grayware
                      first_seen: '2024-11-07T03:24:36Z'
                      last_seen: '2025-11-18T02:10:07Z'
                      registrar: example-registrar
                      registration_date: '2026-04-16'
                      ip_addresses: *id001
                    - domain: api.example.com
                      category: advanced
                      risk_level: low
                      risk_score: 5.81
                      dns_security_category: grayware
                      first_seen: '2024-11-07T03:24:36Z'
                      last_seen: '2025-11-18T02:10:07Z'
                      registrar: example-registrar
                      registration_date: '2026-04-16'
                      ip_addresses: *id001
        '400':
          description: Invalid request parameters or too many domains requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomainBulk400Example:
                  summary: Default getDomainBulk 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '401':
          description: Invalid or missing X-DNS-API-APIKEY header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomainBulk401Example:
                  summary: Default getDomainBulk 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '403':
          description: DNS Security subscription not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomainBulk403Example:
                  summary: Default getDomainBulk 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetDomainBulk500Example:
                  summary: Default getDomainBulk 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stats/network:
    get:
      operationId: getNetworkStats
      summary: Palo Alto Networks Get Network Access Statistics
      description: >-
        Returns DNS query and network access statistics for a customer's
        environment within a specified time range. Supports filtering by
        domain to return per-domain statistics. Useful for monitoring DNS
        query volumes, identifying anomalous lookup patterns, and generating
        compliance reports on DNS Security policy enforcement activity.
      tags:
      - Statistics
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer ID for which to return network statistics.
        schema:
          type: string
        example: '509945'
      - name: domain
        in: query
        required: false
        description: >-
          Filter statistics to a specific domain. When omitted, aggregate
          statistics for all domains are returned.
        schema:
          type: string
        example: api.test-corp.net
      - name: stime
        in: query
        required: true
        description: >-
          Start time for the statistics period in ISO 8601 format or Unix
          epoch seconds.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        required: true
        description: >-
          End time for the statistics period in ISO 8601 format or Unix
          epoch seconds.
        schema:
          type: string
        example: example-etime
      responses:
        '200':
          description: Network access statistics returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkStats'
              examples:
                GetNetworkStats200Example:
                  summary: Default getNetworkStats 200 response
                  x-microcks-default: true
                  value:
                    customerid: '251301'
                    period: &id002
                      start: example-start
                      end: example-end
                    total_queries: 301
                    blocked_queries: 169
                    allowed_queries: 331
                    sinkholed_queries: 260
                    top_queried_domains: &id003
                    - domain: vpn.acme-systems.org
                      query_count: 57
                      dns_security_category: advanced
                    category_breakdown: &id004
                    - category: custom
                      count: 310
                      percentage: 40.54
        '400':
          description: Invalid query parameters or time range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats400Example:
                  summary: Default getNetworkStats 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '401':
          description: Invalid or missing X-DNS-API-APIKEY header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats401Example:
                  summary: Default getNetworkStats 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '403':
          description: DNS Security subscription not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats403Example:
                  summary: Default getNetworkStats 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats500Example:
                  summary: Default getNetworkStats 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    dnsApiKey:
      type: apiKey
      in: header
      name: X-DNS-API-APIKEY
      description: >-
        DNS Security API key. Requires an active DNS Security subscription
        associated with a Palo Alto Networks support account. Obtain from
        the DNS Security portal under API settings.
  schemas:
    DomainDetail:
      type: object
      properties:
        domain:
          type: string
          description: Fully qualified domain name queried.
          example: api.example.com
        category:
          type: string
          description: >-
            URL filtering category assigned to the domain (e.g., malware,
            phishing, command-and-control, business-and-economy).
          example: advanced
        risk_level:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
          description: Risk level assessment for the domain.
          example: low
        risk_score:
          type: number
          format: float
          description: Numeric risk score from 0.0 (no risk) to 100.0 (critical risk).
          minimum: 0.0
          maximum: 100.0
          example: 5.81
        dns_security_category:
          type: string
          enum:
          - benign
          - malware
          - phishing
          - command-and-control
          - grayware
          - dynamic-dns
          - newly-registered
          - parked
          - unknown
          description: DNS Security category classification used for policy enforcement.
          example: grayware
        first_seen:
          type: string
          format: date-time
          description: Timestamp when the domain was first observed by DNS Security.
          example: '2024-11-07T03:24:36Z'
        last_seen:
          type: string
          format: date-time
          description: Timestamp when the domain was most recently observed.
          example: '2025-11-18T02:10:07Z'
        registrar:
          type: string
          description: Domain registrar name.
          example: example-registrar
        registration_date:
          type: string
          format: date
          description: Date the domain was registered.
          example: '2026-04-16'
        ip_addresses:
          type: array
          items:
            type: string
          description: Current IP addresses the domain resolves to.
          example: *id001
    NetworkStats:
      type: object
      properties:
        customerid:
          type: string
          description: Customer ID for which statistics are returned.
          example: '251301'
        period:
          type: object
          properties:
            start:
              type: string
              description: Start of the statistics period.
              example: example-start
            end:
              type: string
              description: End of the statistics period.
              example: example-end
          example: *id002
        total_queries:
          type: integer
          description: Total DNS queries processed during the period.
          example: 301
        blocked_queries:
          type: integer
          description: DNS queries blocked by DNS Security policy.
          example: 169
        allowed_queries:
          type: integer
          description: DNS queries allowed by DNS Security policy.
          example: 331
        sinkholed_queries:
          type: integer
          description: DNS queries redirected to sinkhole.
          example: 260
        top_queried_domains:
          type: array
          description: Most frequently queried domains during the period.
          items:
            type: object
            properties:
              domain:
                type: string
                example: api.example.com
              query_count:
                type: integer
                example: 628
              dns_security_category:
                type: string
                example: standard
          example: *id003
        category_breakdown:
          type: array
          description: Query counts grouped by DNS Security category.
          items:
            type: object
            properties:
              category:
                type: string
                example: custom
              count:
                type: integer
                example: 698
              percentage:
                type: number
                format: float
                example: 66.42
          example: *id004
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the error type.
          example: example-error
        message:
          type: string
          description: Human-readable description of the error.
          example: Security monitoring rule detected on threat network suspicious.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: 583d1742-dcda-461e-a765-4a0c8e530ab5