Palo Alto Networks Domains API

openapi: 3.2.0
info:
  title: Palo Alto Networks DNS Security Domains 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.
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:
                    - 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:
                      - 10.176.161.210
                      - 10.152.189.212
                    - 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:
                      - 10.176.161.210
                      - 10.152.189.212
        '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
components:
  schemas:
    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
    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:
          - 10.176.161.210
          - 10.152.189.212
  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.