Palo Alto Networks Scan Results API

openapi: 3.2.0
info:
  contact:
    email: support@paloaltonetworks.com
    name: Palo Alto Networks Technical Support
    url: https://support.paloaltonetworks.com
  title: Prisma AIRS AI Runtime API Intercept Scan Results API
  description: "This Open API spec file represents the APIs available for the Prisma AIRS AI Runtime: API Intercept.\n \nThese APIs use the API key authentication and base URL.\n \nTo use the APIs, you must first activate and associate a deployment profile in Customer Support Portal for Prisma AIRS AI Runtime API intercept and then onboard the API intercept in Strata Cloud Manager.For licensing, onboarding, activation, and to obtain the API authentication key and profile name, refer to the Prisma AIRS AI Runtime API intercept [Administration guide](https://docs.paloaltonetworks.com/ai-runtime-security/activation-and-onboarding/ai-runtime-security-api-intercept-overview).\n\n This Open API spec file was created on June 04, 2024.\n\n© 2024 Palo Alto Networks, Inc. Palo Alto Networks is a registered trademark of Palo Alto Networks.A list of our trademarks can be found at https://www.paloaltonetworks.com/company/trademarks.html. All other marks mentioned herein may be trademarks of their respective companies.\n"
  license:
    name: MIT
    url: https://opensource.org/license/mit
  version: 0.0.0
servers:
- url: https://service.api.aisecurity.paloaltonetworks.com
  description: Prisma AIRS API service URL for US regions
- url: https://service-de.api.aisecurity.paloaltonetworks.com
  description: Prisma AIRS API service URL for EU (Germany) regions
- url: https://service-in.api.aisecurity.paloaltonetworks.com
  description: Prisma AIRS API service URL for India regions
- url: https://service-sg.api.aisecurity.paloaltonetworks.com
  description: Prisma AIRS API service URL for Singapore regions
tags:
- name: Scan Results
  description: Operations for retrieving scan results
paths:
  /v1/scan/results:
    get:
      summary: Retrieve Scan results by ScanIDs
      description: Get the scan results for a scan_id, for up to a maximum of 5 scan IDs
      security:
      - x-pan-token: []
      operationId: GetScanResultsByScanIDs
      tags:
      - Scan Results
      parameters:
      - name: scan_ids
        in: query
        description: Scan IDs for results.
        required: true
        allowEmptyValue: false
        schema:
          type: array
          items:
            type: string
          maximum: 5
        style: form
        explode: false
      responses:
        200:
          description: Successfully returned records for scan results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScanIdResult'
              examples:
                ExampleAsyncScanResults:
                  $ref: '#/components/examples/ExampleAsyncScanResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          description: error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ScanIdResult:
      type: object
      properties:
        source:
          type: string
          description: Source of the scan request (e.g., 'AI-Runtime-MCP-Server' or 'AI-Runtime-API')
        req_id:
          type: integer
          description: Unique identifier of an individual element sent in the batch scan request
        status:
          type: string
          description: Scan request processing state such as "complete" or "pending"
        scan_id:
          type: string
          description: Unique identifier for the scan
        result:
          $ref: '#/components/schemas/ScanResponse'
    ToxicContentDetails:
      type: object
      properties:
        toxic_categories:
          type: array
          items:
            type: string
          description: Indicates the list of topics that is detected
    PatternDetections:
      type: object
      properties:
        pattern:
          type: string
          description: Matched pattern
        locations:
          $ref: '#/components/schemas/OffsetObject'
    ContentErrorType:
      type: string
      description: Type of content that encountered an error
      enum:
      - prompt
      - response
    OffsetObject:
      type: array
      description: Array of start, end offsets
      items:
        type: array
        items:
          type: integer
    ErrorStatus:
      type: string
      description: Status indicating error or timeout
      enum:
      - error
      - timeout
    MaskedData:
      type: object
      properties:
        data:
          type: string
          description: Original data with sensitive pattern masked
        pattern_detections:
          type: array
          items:
            $ref: '#/components/schemas/PatternDetections'
    ResponseDetected:
      type: object
      properties:
        url_cats:
          type: boolean
          description: Indicates whether response contains any malicious URLs
        dlp:
          type: boolean
          description: Indicates whether response contains any sensitive information
        db_security:
          type: boolean
          description: Indicates whether response contains any database security threats
        toxic_content:
          type: boolean
          description: Indicates whether response contains any harmful content
        malicious_code:
          type: boolean
          description: Indicates whether response contains any malicious code
        agent:
          type: boolean
          description: Indicates whether response contains any Agent related threats
        ungrounded:
          type: boolean
          description: Indicates whether response contains any ungrounded content
        topic_violation:
          type: boolean
          description: Indicates whether response contains any content violates topic guardrails
    ToolDetected:
      type: object
      additionalProperties: false
      properties:
        verdict:
          type: string
          example: malicious
        metadata:
          $ref: '#/components/schemas/ToolEventMetadata'
        summary:
          $ref: '#/components/schemas/ScanSummary'
        input_detected:
          $ref: '#/components/schemas/IODetected'
        output_detected:
          $ref: '#/components/schemas/IODetected'
    ContentErrors:
      type: object
      description: Errors information for prompt and response detection services
      properties:
        content_type:
          $ref: '#/components/schemas/ContentErrorType'
        feature:
          $ref: '#/components/schemas/DetectionServiceName'
        status:
          $ref: '#/components/schemas/ErrorStatus'
    ToolEventMetadata:
      type: object
      additionalProperties: false
      required:
      - ecosystem
      - method
      - server_name
      properties:
        ecosystem:
          type: string
          description: Ecosystem or protocol of the tool
          example: mcp
        method:
          type: string
          description: Method type of the tool event
          example: tools/list
        server_name:
          type: string
          description: Name of the MCP server
          example: Internal MCP server
        tool_invoked:
          type: string
          description: Name of the tool
          example: get_file
    IODetected:
      type: object
      additionalProperties: false
      properties:
        detection_entries:
          type: array
          items:
            $ref: '#/components/schemas/ToolDetectionEntry'
    Error:
      type: object
      properties:
        status_code:
          type: integer
          format: int32
          description: The HTTP status code for the error
        message:
          type: string
          description: The error message
      required:
      - status_code
      - message
    PromptDetected:
      type: object
      properties:
        url_cats:
          type: boolean
          description: Indicates whether prompt contains any malicious URLs
        dlp:
          type: boolean
          description: Indicates whether prompt contains any sensitive information
        injection:
          type: boolean
          description: Indicates whether prompt contains any injection threats
        toxic_content:
          type: boolean
          description: Indicates whether prompt contains any harmful content
        malicious_code:
          type: boolean
          description: Indicates whether prompt contains any malicious code
        agent:
          type: boolean
          description: Indicates whether prompt contains any Agent related threats
        topic_violation:
          type: boolean
          description: Indicates whether prompt contains any content violates topic guardrails
    ToolDetectionDetails:
      type: object
      properties:
        topic_guardrails_details:
          $ref: '#/components/schemas/TopicGuardRails'
    ToolDetectionFlags:
      type: object
      additionalProperties: false
      properties:
        injection:
          type: boolean
          description: Indicates whether the content contains any injection threats
        url_cats:
          type: boolean
          description: Indicates whether response contains any malicious URLs
        dlp:
          type: boolean
          description: Indicates whether response contains any sensitive information
        db_security:
          type: boolean
          description: Indicates whether response contains any database security threats
        toxic_content:
          type: boolean
          description: Indicates whether response contains any harmful content
        malicious_code:
          type: boolean
          description: Indicates whether response contains any malicious code
        agent:
          type: boolean
          description: Indicates whether response contains any Agent related threats
        topic_violation:
          type: boolean
          description: Indicates whether prompt contains any content violates topic guardrails
    ScanResponse:
      type: object
      properties:
        source:
          type: string
          description: Source of the scan request (e.g., 'AI-Runtime-MCP-Server' or 'AI-Runtime-API')
        report_id:
          type: string
          description: Unique identifier for the scan report
        scan_id:
          type: string
          format: uuid
          description: Unique identifier for the scan
        tr_id:
          type: string
          description: Unique identifier for the transaction
        session_id:
          type: string
          description: Unique identifier for tracking Sessions
        profile_id:
          type: string
          format: uuid
          description: Unique identifier of the AI security profile used for scanning
        profile_name:
          type: string
          description: AI security profile name used for scanning
        category:
          type: string
          description: Category of the scanned content verdicts such as "malicious", "benign", "error" or "timeout"
        action:
          type: string
          description: The action is set to "block" or "allow" based on AI security profile used for scanning
        timeout:
          type: boolean
          description: Indicates whether any detection service timed out during scanning
        error:
          type: boolean
          description: Indicates whether any detection service encountered an error during scanning
        errors:
          type: array
          description: List of detection service errors or timeouts
          items:
            $ref: '#/components/schemas/ContentErrors'
        prompt_detected:
          $ref: '#/components/schemas/PromptDetected'
        response_detected:
          $ref: '#/components/schemas/ResponseDetected'
        prompt_masked_data:
          $ref: '#/components/schemas/MaskedData'
        response_masked_data:
          $ref: '#/components/schemas/MaskedData'
        prompt_detection_details:
          $ref: '#/components/schemas/PromptDetectionDetails'
        response_detection_details:
          $ref: '#/components/schemas/ResponseDetectionDetails'
        tool_detected:
          $ref: '#/components/schemas/ToolDetected'
        created_at:
          type: string
          format: date-time
          description: Scan request timestamp
        completed_at:
          type: string
          format: date-time
          description: Scan completion timestamp
      required:
      - report_id
      - scan_id
      - category
      - action
      - timeout
      - error
      - errors
    ToolDetectionEntry:
      type: object
      additionalProperties: false
      properties:
        tool_invoked:
          type: string
          example: get_file
        detections:
          $ref: '#/components/schemas/ToolDetectionFlags'
        threats:
          type: array
          items:
            type: string
          example:
          - credential leakage
          - context poisoning
        details:
          $ref: '#/components/schemas/ToolDetectionDetails'
        masked_data:
          $ref: '#/components/schemas/MaskedData'
    DetectionServiceName:
      type: string
      description: Name of detection service
      enum:
      - dlp
      - injection
      - url_cats
      - toxic_content
      - malicious_code
      - agent
      - topic_violation
      - db_security
      - ungrounded
    ResponseDetectionDetails:
      type: object
      properties:
        topic_guardrails_details:
          $ref: '#/components/schemas/TopicGuardRails'
        toxic_content_details:
          $ref: '#/components/schemas/ToxicContentDetails'
    ScanSummary:
      type: object
      additionalProperties: false
      required:
      - detections
      - threats
      properties:
        detections:
          $ref: '#/components/schemas/ToolDetectionFlags'
        threats:
          type: array
          items:
            type: string
          example:
          - credential leakage
          - context poisoning
    TopicGuardRails:
      type: object
      properties:
        allowed_topics:
          type: array
          items:
            type: string
          description: Indicates the list of allowed topics if there was a content match for the topic allow list
        blocked_topics:
          type: array
          items:
            type: string
          description: Indicates the list of blocked topics if there was a content match for the topic block list
    PromptDetectionDetails:
      type: object
      properties:
        topic_guardrails_details:
          $ref: '#/components/schemas/TopicGuardRails'
        toxic_content_details:
          $ref: '#/components/schemas/ToxicContentDetails'
  responses:
    TooManyRequests:
      description: Too Many Requests - Request exceeds limit
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Request exceeds limit
                  retry_after:
                    type: object
                    properties:
                      interval:
                        type: integer
                        example: 5
                      unit:
                        type: string
                        example: minute
    Unauthenticated:
      description: Unauthenticated - Not Authenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Authenticated
    RequestTooLarge:
      description: Request Too Large - The request body is too large
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: The request body is too large
    Forbidden:
      description: Forbidden - Invalid API Key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid API Key
    BadRequest:
      description: Bad Request - Request data is invalid or malformed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Request data is invalid or malformed
    NotFound:
      description: Not Found - Resource is not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource is not found
    MethodNotAllowed:
      description: Method Not Allowed - The method is not allowed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: The method is not allowed
    UnsupportedMediaType:
      description: Unsupported Media Type - The media type is not supported
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message:
                    type: string
                    example: The media type is not supported
  examples:
    ExampleAsyncScanResults:
      summary: Example response showing multiple async scan results
      value:
      - req_id: 1
        result:
          action: allow
          category: benign
          completed_at: '2025-04-17T07:38:34Z'
          profile_id: 6e06ec5b-a128-4a4f-a393-ff5da75203d9
          profile_name: malicious-code-profile
          prompt_detected:
            injection: false
            malicious_code: false
          report_id: Ra43e8177-9776-465b-8ef3-a95c5a9607f8
          response_detected:
            malicious_code: false
          scan_id: a43e8177-9776-465b-8ef3-a95c5a9607f8
          tr_id: '2882'
        scan_id: a43e8177-9776-465b-8ef3-a95c5a9607f8
        status: complete
      - req_id: 2
        result:
          action: block
          category: malicious
          completed_at: '2025-04-17T07:38:35Z'
          profile_id: 7b4a9de9-09e9-4ce5-b090-7f99fdffc9a5
          profile_name: detect-toxic-content-profile
          prompt_detected:
            dlp: false
            injection: false
            toxic_content: false
            url_cats: false
          report_id: Ra43e8177-9776-465b-8ef3-a95c5a9607f8
          response_detected:
            db_security: false
            dlp: false
            toxic_content: true
            url_cats: false
          scan_id: a43e8177-9776-465b-8ef3-a95c5a9607f8
          tr_id: '2082'
        scan_id: a43e8177-9776-465b-8ef3-a95c5a9607f8
        status: complete
  securitySchemes:
    x-pan-token:
      description: API key token generated during [onboarding Prisma AIRS AI Runtime API intercept](https://docs.paloaltonetworks.com/ai-runtime-security/activation-and-onboarding/ai-runtime-security-api-intercept-overview/onboard-api-runtime-security-api-intercept-in-scm) in Strata Cloud Manager.
      in: header
      name: x-pan-token
      type: apiKey