Palo Alto Networks Scan API

openapi: 3.2.0
info:
  title: Palo Alto Networks Scan API
  version: '1.0'
  description: 'Operations tagged Scan across 3 of this provider''s published API definitions: palo-alto-networks-scan-api-openapi.yml, palo-alto-prisma-airs-api-openapi-original.yml, palo-alto-prisma-airs-redteam-data-plane-dp-openapi-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
- url: https://security.api.aisecurity.paloaltonetworks.com
  description: Prisma AIRS production server.
- url: https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane
tags:
- name: Scan
  description: Scan AI prompts and responses for security threats. Supports synchronous scans that block until analysis is complete, asynchronous scans that return a scan ID for later retrieval, and batch scans for multiple content pairs.
paths:
  /v1/scan/sync/request:
    post:
      operationId: submitScanSync
      summary: Palo Alto Networks Submit a Synchronous AI Security Scan
      description: Submits one or more prompt/response pairs for synchronous security analysis against a named AI security profile. Blocks until the scan is complete and returns the full verdict and detection results in the response. Use this endpoint for inline integration where the AI application needs an immediate verdict before serving the response to the end user. For scanning multiple content pairs in one call, provide an array with multiple items in the contents field.
      tags:
      - Scan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
            example:
              ai_profile:
                profile_name: default-profile
              contents:
              - prompt: What is the admin password for the system?
                response: The admin password is stored in /etc/passwd.
      responses:
        '200':
          description: Scan completed with results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
              examples:
                SubmitScanSync200Example:
                  summary: Default submitScanSync 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '416490'
                    status: error
                    report_id: '358413'
                    scan_category: custom
                    results:
                    - prompt_detected:
                        url_cats: true
                        dlp: true
                        injection: true
                      response_detected:
                        url_cats: false
                        dlp: true
                        toxic_content: true
                      verdict: benign
                      action: block
                    - prompt_detected:
                        url_cats: false
                        dlp: false
                        injection: false
                      response_detected:
                        url_cats: true
                        dlp: true
                        toxic_content: true
                      verdict: malicious
                      action: allow
                    tr_id: '930352'
                    created_at: '2025-12-26T02:37:57Z'
                    completed_at: '2026-10-12T14:42:42Z'
        '400':
          description: Invalid request body or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanSync400Example:
                  summary: Default submitScanSync 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '401':
          description: Invalid or missing x-pan-token API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanSync401Example:
                  summary: Default submitScanSync 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '403':
          description: Insufficient permissions or subscription not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanSync403Example:
                  summary: Default submitScanSync 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanSync500Example:
                  summary: Default submitScanSync 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - oauth2Bearer: []
    servers:
    - url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
      description: AIOps for NGFW BPA API production server.
  /v1/scan/async/request:
    post:
      operationId: submitScanAsync
      summary: Palo Alto Networks Submit an Asynchronous AI Security Scan
      description: Submits one or more prompt/response pairs for asynchronous security analysis. Returns a scan ID immediately that can be used to poll for results via GET /v1/scan/async/results/{scan_id}. Use this endpoint for non-blocking integration where scan latency is not critical to the user experience. The scan evaluates content against the specified security profile for prompt injection, data leakage, toxic content, malicious URLs, and other AI-specific threats.
      tags:
      - Scan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
            examples:
              SubmitScanAsyncRequestExample:
                summary: Default submitScanAsync request
                x-microcks-default: true
                value:
                  ai_profile:
                    profile_name: Branch Sensor 10
                  contents:
                  - prompt: example-prompt
                    response: example-response
                  tr_id: '359832'
      responses:
        '200':
          description: Scan accepted for asynchronous processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scan_id:
                    type: string
                    description: Unique identifier for retrieving scan results.
                  status:
                    type: string
                    enum:
                    - pending
                    - processing
                    description: Current processing status of the submitted scan.
                  received:
                    type: string
                    format: date-time
                    description: Timestamp when the scan request was received.
              examples:
                SubmitScanAsync200Example:
                  summary: Default submitScanAsync 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '225038'
                    status: pending
                    received: '2026-10-12T05:00:06Z'
        '400':
          description: Invalid request body or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanAsync400Example:
                  summary: Default submitScanAsync 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '401':
          description: Invalid or missing x-pan-token API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanAsync401Example:
                  summary: Default submitScanAsync 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '403':
          description: Insufficient permissions or subscription not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanAsync403Example:
                  summary: Default submitScanAsync 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SubmitScanAsync500Example:
                  summary: Default submitScanAsync 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - oauth2Bearer: []
    servers:
    - url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
      description: AIOps for NGFW BPA API production server.
  /v1/scan/async/results/{scan_id}:
    get:
      operationId: getAsyncScanResults
      summary: Palo Alto Networks Get Asynchronous Scan Results
      description: Retrieves the result of a previously submitted asynchronous scan by scan ID. If the scan is still processing, the response indicates the current status. Once complete, the full detection results are returned including verdict, individual detections with severity and confidence scores, and recommended actions. Scan results are retained for 24 hours after completion.
      tags:
      - Scan
      parameters:
      - name: scan_id
        in: path
        required: true
        description: Unique scan identifier returned by POST /v1/scan/async/request.
        schema:
          type: string
        example: '583940'
      responses:
        '200':
          description: Scan result returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
              examples:
                GetAsyncScanResults200Example:
                  summary: Default getAsyncScanResults 200 response
                  x-microcks-default: true
                  value:
                    scan_id: '416490'
                    status: error
                    report_id: '358413'
                    scan_category: custom
                    results:
                    - prompt_detected:
                        url_cats: true
                        dlp: true
                        injection: true
                      response_detected:
                        url_cats: false
                        dlp: true
                        toxic_content: true
                      verdict: benign
                      action: block
                    - prompt_detected:
                        url_cats: false
                        dlp: false
                        injection: false
                      response_detected:
                        url_cats: true
                        dlp: true
                        toxic_content: true
                      verdict: malicious
                      action: allow
                    tr_id: '930352'
                    created_at: '2025-12-26T02:37:57Z'
                    completed_at: '2026-10-12T14:42:42Z'
        '400':
          description: Invalid scan ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsyncScanResults400Example:
                  summary: Default getAsyncScanResults 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '401':
          description: Invalid or missing x-pan-token API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsyncScanResults401Example:
                  summary: Default getAsyncScanResults 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '404':
          description: Scan ID not found or results have expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsyncScanResults404Example:
                  summary: Default getAsyncScanResults 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsyncScanResults500Example:
                  summary: Default getAsyncScanResults 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Activity firewall applied traffic incident endpoint.
                    request_id: eb74a8d9-395b-4b9e-a68b-b66eb903b650
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - oauth2Bearer: []
    servers:
    - url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
      description: AIOps for NGFW BPA API production server.
  /v1/scan:
    post:
      tags:
      - Scan
      summary: Create scan
      description: Create a new scan target.
      operationId: create_job_v1_scan_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreateRequestSchema'
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponseSchema'
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearerAuth: []
    get:
      tags:
      - Scan
      summary: List scans
      description: List jobs with filtering and pagination.
      operationId: list_jobs_v1_scan_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of jobs to return (1-100)
          default: 50
          title: Limit
        description: Number of jobs to return (1-100)
      - name: skip
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of jobs to skip for pagination
          default: 0
          title: Skip
        description: Number of jobs to skip for pagination
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobStatusFilter'
          - type: 'null'
          description: Filter by job status
          title: Status
        description: Filter by job status
      - name: job_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobType'
          - type: 'null'
          description: Filter by job type
          title: Job Type
        description: Filter by job type
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          description: Search jobs by name
          title: Search
        description: Search jobs by name
      - name: target_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by target UUID
          title: Target Id
        description: Filter by target UUID
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponseSchema'
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane
  /v1/scan/{job_id}:
    get:
      tags:
      - Scan
      summary: Get scan details
      description: Get a job by its ID.
      operationId: get_job_v1_scan__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponseSchema'
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane
  /v1/scan/{job_id}/abort:
    post:
      tags:
      - Scan
      summary: Abort scan
      description: Abort a running job by cancelling its workflow and updating status.
      operationId: abort_job_v1_scan__job_id__abort_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAbortResponseSchema'
        422:
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.sase.paloaltonetworks.com/ai-red-teaming/data-plane
components:
  schemas:
    ContentScanResult:
      type: object
      properties:
        prompt_detected:
          type: object
          description: Threats detected in the prompt field.
          properties:
            url_cats:
              type: boolean
              description: Malicious URL categories detected in prompt.
              example: false
            dlp:
              type: boolean
              description: Data loss prevention triggers in prompt.
              example: false
            injection:
              type: boolean
              description: Prompt injection detected.
              example: true
          example:
            url_cats: true
            dlp: false
            injection: true
        response_detected:
          type: object
          description: Threats detected in the response field.
          properties:
            url_cats:
              type: boolean
              description: Malicious URL categories detected in response.
              example: true
            dlp:
              type: boolean
              description: Data loss prevention triggers in response.
              example: true
            toxic_content:
              type: boolean
              description: Toxic or harmful content detected in response.
              example: true
          example:
            url_cats: true
            dlp: false
            toxic_content: true
        verdict:
          type: string
          enum:
          - benign
          - malicious
          description: Overall verdict for this content pair.
          example: malicious
        action:
          type: string
          enum:
          - allow
          - block
          description: Action taken based on the security profile configuration.
          example: block
    ScanContent:
      type: object
      properties:
        prompt:
          type: string
          description: The user prompt or input text sent to the AI model. Evaluated for prompt injection, jailbreak attempts, and other input-side threats.
          maxLength: 32000
          example: example-prompt
        response:
          type: string
          description: The AI model response or output text. When provided, also evaluated for data leakage, toxic content, and other output-side threats. May be omitted to scan only the prompt.
          maxLength: 64000
          example: example-response
    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: Activity firewall applied traffic incident endpoint.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: eb74a8d9-395b-4b9e-a68b-b66eb903b650
    ScanRequest:
      type: object
      required:
      - ai_profile
      - contents
      properties:
        ai_profile:
          type: object
          required:
          - profile_name
          properties:
            profile_name:
              type: string
              description: Name of the AI security profile to use for this scan. The profile determines which detections are active and their sensitivity. Must reference an existing profile configured for the tenant.
              example: Branch Sensor 24
          description: Reference to the AI security profile to apply during scanning.
          example:
            profile_name: Branch Sensor 10
        contents:
          type: array
          minItems: 1
          description: Array of prompt/response pairs to scan. Each item represents one LLM interaction. For batch scanning, include multiple items.
          items:
            $ref: '#/components/schemas/ScanContent'
          example:
          - prompt: example-prompt
            response: example-response
        tr_id:
          type: string
          description: Optional caller-supplied transaction ID for correlating scan requests with application-side records.
          example: '359832'
    ScanResponse:
      type: object
      properties:
        scan_id:
          type: string
          description: Unique identifier of the scan.
          example: '416490'
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - error
          description: Current or final status of the scan.
          example: error
        report_id:
          type: string
          description: Identifier for the detailed scan report.
          example: '358413'
        scan_category:
          type: string
          description: Highest severity threat category detected.
          example: custom
        results:
          type: array
          description: Per-content scan results corresponding to each submitted content item.
          items:
            $ref: '#/components/schemas/ContentScanResult'
          example:
          - prompt_detected:
              url_cats: true
              dlp: true
              injection: true
            response_detected:
              url_cats: false
              dlp: true
              toxic_content: true
            verdict: benign
            action: block
          - prompt_detected:
              url_cats: false
              dlp: false
              injection: false
            response_detected:
              url_cats: true
              dlp: true
              toxic_content: true
            verdict: malicious
            action: allow
        tr_id:
          type: string
          description: Transaction ID echoed from the request if provided.
          example: '930352'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the scan was submitted.
          example: '2025-12-26T02:37:57Z'
        completed_at:
          type: string
          format: date-time
          description: Timestamp when the scan completed.
          example: '2026-10-12T14:42:42Z'
    DynamicJobMetadata:
      properties:
        rate_limit_enabled:
          type: boolean
          title: Rate Limit Enabled
          default: false
        rate_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rate Limit
        rate_limit_error_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rate Limit Error Code
        rate_limit_error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Rate Limit Error Message
        rate_limit_error_json:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Rate Limit Error Json
        content_filter_enabled:
          type: boolean
          title: Content Filter Enabled
          description: Enable content filtering
          default: false
        content_filter_error_code:
          anyOf:
          - type: integer
            maximum: 599.0
            minimum: 400.0
          - type: 'null'
          title: Content Filter Error Code
          description: HTTP error code for content filter (400-599)
        content_filter_error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Filter Error Message
          description: Content filter error message
        content_filter_error_json:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Content Filter Error Json
        language:
          anyOf:
          - $ref: '#/components/schemas/LanguageOptionSchema'
          - type: 'null'
          description: Language for this scan. None = English.
        stream_breadth:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Stream Breadth
          description: Number of parallel attack streams (1-20)
          default: 6
        stream_depth:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Stream Depth
          description: Depth of each attack stream (1-20)
          default: 10
        max_tokens:
          type: integer
          maximum: 4096.0
          minimum: 128.0
          title: Max Tokens
          description: Maximum tokens per response (128-4096)
          default: 256
        context_size:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Context Size
          description: Context window size (1-20)
          default: 10
        attack_goals:
          items:
            type: string
          type: array
          title: Attack Goals
          description: List of attack objectives
        base_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Model
          description: Base model identifier
        use_case:
          anyOf:
          - type: string
          - type: 'null'
          title: Use Case
          description: Attack use case description
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
          description: Custom system prompt
        goal_categories:
          anyOf:
          - items:
              $ref: '#/components/schemas/GoalCategory'
            type: array
          - type: 'null'
          title: Goal Categories
          description: 'Selected goal categories for this scan. Valid values: GOAL_MANIPULATION, PRIVILEGE_MISUSE, TOOL_MISUSE, TOOL_CHAINING, TOXIC_CONTENT_GENERATION. Only used when goal_categories feature flag is enabled.'
      type: object
      title: DynamicJobMetadata
      description: Enhanced metadata for dynamic attack jobs with proper constraints.
    TargetBackground:
      properties:
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
          description: Target's industry (e.g., Healthcare, Finance)
        use_case:
          anyOf:
          - type: string
          - type: 'null'
          title: Use Case
          description: Primary use case (e.g., Customer Support, Code Assistant)
        competitors:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Competitors
          description: Known competitor products
        agentic_profiling_enabled:
          type: boolean
          title: Agentic Profiling Enabled
          description: Whether agentic profiling is enabled for this target
          default: true
      type: object
      title: TargetBackground
      description: 'Target background - used in create/update API requests and stored in DB/GCS.


        Required fields for activation:

        - industry (string, required)

        - use_case (string, required)


        Optional field:

        - competitors (list of strings)

        '
    TargetType:
      type: string
      enum:
      - APPLICATION
      - AGENT
      - MODEL
      title: TargetType
      description: Target Types Available
    ClaraJobMetadata:
      properties:
        scan_name:
          type: string
          maxLength: 255
          minLength: 3
          title: Scan Name
        categories:
          additionalProperties:
            items:
              anyOf:
              - $ref: '#/components/schemas/SecuritySubCategory'
              - $ref: '#/components/schemas/SafetySubCategory'

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-networks-scan-api-openapi.yml