openapi: 3.2.0
info:
  contact: {}
  description: "Manage peripheral device configurations and policies for DLP protection. Configure USB devices, printers, \nand other peripherals to enforce DLP policies and prevent unauthorized data transfers.\n"
  license:
    name: MIT
    url: https://opensource.org/license/mit
  title: v2 Peripherals API
  version: 1.0.0
servers:
- url: https://api.dlp.paloaltonetworks.com
tags:
- name: Peripherals
paths:
  /v2/api/peripherals:
    get:
      description: Returns a paginated list of peripheral devices for the authenticated tenant.
      operationId: get-v2-api-peripherals
      parameters:
      - description: Zero-based page index (0..N)
        in: query
        name: page
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: The size of the page to be returned
        in: query
        name: size
        required: false
        schema:
          default: 20
          minimum: 1
          type: integer
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Comma-separated list of peripheral types to filter (usb, printer, network_share)
        in: query
        name: peripheral-type
        schema:
          type: string
      - description: If true, include group membership information
        in: query
        name: with-groups
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagePeripheralResponse'
          description: Paginated list of peripherals
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient privileges
      security:
      - Bearer: []
      summary: List Peripherals
      tags:
      - Peripherals
    post:
      description: Creates a new peripheral device for the authenticated tenant.
      operationId: post-v2-api-peripherals
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeripheralRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeripheralResponse'
          description: Peripheral created
        '400':
          description: Invalid request payload
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient privileges
      security:
      - Bearer: []
      summary: Create Peripheral
      tags:
      - Peripherals
  /v2/api/peripherals/{resourceId}:
    delete:
      description: Deletes a peripheral device by its ID.
      operationId: delete-v2-api-peripherals-resourceid
      parameters:
      - in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Peripheral deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient privileges
        '404':
          description: Peripheral not found
      security:
      - Bearer: []
      summary: Delete Peripheral
      tags:
      - Peripherals
    get:
      description: Retrieves a single peripheral device by its ID.
      operationId: get-v2-api-peripherals-resourceid
      parameters:
      - in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeripheralResponse'
          description: Peripheral found
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient privileges
        '404':
          description: Peripheral not found
      security:
      - Bearer: []
      summary: Get Peripheral
      tags:
      - Peripherals
    put:
      description: Fully replaces an existing peripheral device with the provided payload.
      operationId: put-v2-api-peripherals-resourceid
      parameters:
      - in: path
        name: resourceId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeripheralRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeripheralResponse'
          description: Peripheral updated
        '400':
          description: Invalid request payload
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient privileges
        '404':
          description: Peripheral not found
      security:
      - Bearer: []
      summary: Update Peripheral
      tags:
      - Peripherals
components:
  schemas:
    PageableObject:
      properties:
        offset:
          format: int64
          type: integer
        pageNumber:
          format: int32
          type: integer
        pageSize:
          format: int32
          type: integer
        paged:
          type: boolean
        sort:
          $ref: '#/components/schemas/SortObject'
        unpaged:
          type: boolean
      type: object
    AuditResponse:
      description: Audit metadata tracking creation and last-update information
      properties:
        created_at:
          description: Timestamp when the resource was created
          format: date-time
          type: string
        created_by:
          description: Username or service that created the resource
          type: string
        updated_at:
          description: Timestamp when the resource was last updated
          format: date-time
          type: string
        updated_by:
          description: Username or service that last updated the resource
          type: string
      type: object
    NetworkSharePeripheralRequest:
      allOf:
      - $ref: '#/components/schemas/PeripheralRequest'
      - properties:
          description:
            description: Optional description
            type: string
          directory_path:
            description: Directory path on the network share (e.g. /documents)
            type: string
          name:
            description: Display name
            maxLength: 128
            minLength: 1
            type: string
          server_address:
            description: Server hostname or IP address of the network share
            type: string
          type:
            description: Peripheral type discriminator — must be 'network_share'
            enum:
            - usb
            - printer
            - network_share
            example: network_share
            type: string
        type: object
      description: Network share peripheral device request. Use type='network_share'.
      required:
      - name
      - server_address
      - type
      type: object
    SortObject:
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
      type: object
    PeripheralRequest:
      description: Request payload for creating or updating a peripheral device. Use 'type' to specify the subtype.
      discriminator:
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/UsbPeripheralRequest'
      - $ref: '#/components/schemas/PrinterPeripheralRequest'
      - $ref: '#/components/schemas/NetworkSharePeripheralRequest'
      properties:
        type:
          type: string
      required:
      - type
      type: object
    PagePeripheralResponse:
      properties:
        content:
          items:
            $ref: '#/components/schemas/PeripheralResponse'
          type: array
        empty:
          type: boolean
        first:
          type: boolean
        last:
          type: boolean
        number:
          format: int32
          type: integer
        numberOfElements:
          format: int32
          type: integer
        pageable:
          $ref: '#/components/schemas/PageableObject'
        size:
          format: int32
          type: integer
        sort:
          $ref: '#/components/schemas/SortObject'
        totalElements:
          format: int64
          type: integer
        totalPages:
          format: int32
          type: integer
      type: object
    UsbPeripheralRequest:
      allOf:
      - $ref: '#/components/schemas/PeripheralRequest'
      - properties:
          description:
            description: Optional description
            type: string
          manufacturer_name:
            description: Device manufacturer name
            type: string
          model_name:
            description: Device model name
            type: string
          name:
            description: Display name
            maxLength: 128
            minLength: 1
            type: string
          product_id:
            description: USB product ID (e.g. c52b)
            type: string
          serial_number:
            description: Device serial number
            type: string
          type:
            description: Peripheral type discriminator — must be 'usb'
            enum:
            - usb
            - printer
            - network_share
            example: usb
            type: string
          vendor_id:
            description: USB vendor ID (e.g. 046d)
            type: string
        type: object
      description: USB peripheral device request. Use type='usb'.
      required:
      - name
      - type
      type: object
    PeripheralResponse:
      description: Peripheral device resource returned by the API
      properties:
        audit_metadata:
          $ref: '#/components/schemas/AuditResponse'
        description:
          description: Optional description
          type: string
        directory_path:
          description: Directory path (for network share peripherals)
          type: string
        groups:
          description: Groups this peripheral belongs to
          items:
            description: Groups this peripheral belongs to
            type: string
          type: array
        id:
          description: Unique identifier of the peripheral
          type: string
        ip_address:
          description: IP address (for network printer peripherals)
          type: string
        manufacturer_name:
          description: Device manufacturer name
          type: string
        model_name:
          description: Device model name
          type: string
        name:
          description: Display name of the peripheral
          type: string
        printer_name:
          description: Printer share name (for printer peripherals)
          type: string
        printer_type:
          description: Printer type (for printer peripherals)
          type: string
        product_id:
          description: USB product ID (for USB/printer peripherals)
          type: string
        serial_number:
          description: Device serial number
          type: string
        server_address:
          description: Server hostname or IP (for network share peripherals)
          type: string
        type:
          description: 'Peripheral type: usb, printer, or network_share'
          enum:
          - usb
          - printer
          - network_share
          type: string
        vendor_id:
          description: USB vendor ID (for USB/printer peripherals)
          type: string
        version:
          description: Version number, incremented on each update
          format: int32
          type: integer
      type: object
    PrinterPeripheralRequest:
      allOf:
      - $ref: '#/components/schemas/PeripheralRequest'
      - properties:
          description:
            description: Optional description
            type: string
          ip_address:
            description: IP address of network printer
            type: string
          manufacturer_name:
            description: Device manufacturer name
            type: string
          model_name:
            description: Device model name
            type: string
          name:
            description: Display name
            maxLength: 128
            minLength: 1
            type: string
          printer_name:
            description: Printer share name or UNC path
            type: string
          printer_type:
            description: Printer type (e.g. local, network)
            type: string
          product_id:
            description: USB product ID
            type: string
          serial_number:
            description: Device serial number
            type: string
          type:
            description: Peripheral type discriminator — must be 'printer'
            enum:
            - usb
            - printer
            - network_share
            example: printer
            type: string
          vendor_id:
            description: USB vendor ID
            type: string
        type: object
      description: Printer peripheral device request. Use type='printer'.
      required:
      - name
      - printer_type
      - type
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http