openapi: 3.2.0
info:
  version: 2.0.0
  title: Device Onboarding Site Groups API
  description: These APIs are used to define Strata Cloud Manager device onboarding workflows.
  termsOfService: https://www.paloaltonetworks.com/content/dam/pan/en_US/assets/pdf/legal/palo-alto-networks-end-user-license-agreement-eula.pdf
  contact:
    email: support@paloaltonetworks.com
    name: Palo Alto Networks Technical Support
    url: https://support.paloaltonetworks.com
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
- url: https://api.strata.paloaltonetworks.com/config/setup/device-onboarding/v1
  description: Current
security:
- scmToken: []
tags:
- name: Site Groups
  description: Onboarding Site Groups Information
paths:
  /site-groups:
    post:
      tags:
      - Site Groups
      summary: Create a site group
      description: 'Creates a new site group with optional property list. The property list defines

        which properties are available for sites in this site group and which properties

        can be referenced by onboarding rule variables for this site group.

        '
      operationId: createSiteGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_site_group_request'
      responses:
        '201':
          description: Site group created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Response status indicator
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Site group ID
                      name:
                        type: string
                        description: Site group name
                  message:
                    type: string
                    description: Human-readable message
                  request_id:
                    type: string
                    format: uuid
                    description: Unique request identifier for troubleshooting
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Site Groups
      summary: List site groups
      description: Retrieves all site groups for the tenant
      operationId: listSiteGroups
      responses:
        '200':
          description: Site groups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Response status indicator
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/site_group'
                    description: Array of site groups
                  message:
                    type: string
                    description: Human-readable message
                  request_id:
                    type: string
                    format: uuid
                    description: Unique request identifier for troubleshooting
        '500':
          $ref: '#/components/responses/InternalServerError'
  /site-groups/{id}:
    get:
      tags:
      - Site Groups
      summary: Get a site group
      description: Retrieves a site group by UUID
      operationId: getSiteGroupByID
      parameters:
      - $ref: '#/components/parameters/site_group_id'
      responses:
        '200':
          description: Site group retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Response status indicator
                  data:
                    $ref: '#/components/schemas/site_group'
                    description: Site group details
                  message:
                    type: string
                    description: Human-readable message
                  request_id:
                    type: string
                    format: uuid
                    description: Unique request identifier for troubleshooting
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Site Groups
      summary: Update a site group
      description: 'Updates a site group''s name, description, or property list.


        **Validation rules:**

        - Name changes are blocked (HTTP 409) if the site group is referenced by any sites or onboarding rules

        - Property list updates are blocked (HTTP 409) if any unclaimed sites reference this site group

        - Property list updates are allowed if all sites referencing this site group are claimed

        - Description-only updates are always allowed

        '
      operationId: updateSiteGroupByID
      parameters:
      - $ref: '#/components/parameters/site_group_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_site_group_request'
      responses:
        '200':
          description: Site group updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Response status indicator
                  data:
                    $ref: '#/components/schemas/site_group'
                    description: Updated site group
                  message:
                    type: string
                    description: Human-readable message
                  request_id:
                    type: string
                    format: uuid
                    description: Unique request identifier for troubleshooting
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Site Groups
      summary: Delete a site group
      description: 'Deletes a site group by ID. Site group must not be in use by any sites or onboarding rules.

        '
      operationId: deleteSiteGroupByID
      parameters:
      - $ref: '#/components/parameters/site_group_id'
      responses:
        '200':
          description: Site group deleted successfully - returns deleted resource
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Response status indicator
                  data:
                    $ref: '#/components/schemas/site_group'
                    description: Deleted site group
                  message:
                    type: string
                    description: Human-readable message
                  request_id:
                    type: string
                    format: uuid
                    description: Unique request identifier for troubleshooting
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    site_group_id:
      name: id
      in: path
      required: true
      description: Site Group UUID
      schema:
        type: string
        format: uuid
  schemas:
    site_group:
      type: object
      required:
      - id
      - tenant_id
      - name
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
        name:
          type: string
          description: Site group name (unique within tenant)
        description:
          type: string
        properties:
          type: array
          items:
            type: string
          description: 'List of property names that are available for sites in this site group.

            This defines which properties can be used in site property_values and which

            properties can be referenced by onboarding rule variables for this site group.'
        created_at:
          type: string
          format: date-time
        last_updated:
          type: string
          format: date-time
    resource_validation_result:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Resource UUID
        name:
          type: string
          description: Resource name
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/resource_validation_error'
    update_site_group_request:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Site group name (unique within tenant)
        description:
          type: string
          description: Optional description of the site group
        properties:
          type: array
          items:
            type: string
          description: 'Optional list of property names (not UUIDs) that define the property schema

            for this site group. Property list updates are blocked if any unclaimed sites

            reference this site group.'
          example:
          - region_id
          - site_id
    resource_validation_error:
      type: object
      required:
      - type
      - resource_id
      - resource_name
      - message
      properties:
        type:
          type: string
          enum:
          - site
          - rule
          - name_conflict
          description: Type of validation error
        resource_id:
          type: string
          description: ID of the affected resource
        resource_name:
          type: string
          description: Name of the affected resource
        message:
          type: string
          description: Detailed error message
    create_site_group_request:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Site group name (unique within tenant)
        description:
          type: string
          description: Optional description of the site group
        properties:
          type: array
          items:
            type: string
          description: 'Optional list of property names (not UUIDs) that define the property schema

            for this site group. Sites in this group must use properties from this list,

            and onboarding rule variables for this site group can only reference properties

            from this list.'
          example:
          - region_id
          - site_id
          - location
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - error
            properties:
              status:
                type: string
                enum:
                - error
              error:
                type: string
                description: Error message
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - error
            properties:
              status:
                type: string
                enum:
                - error
              error:
                type: string
                description: Error message
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - error
            properties:
              status:
                type: string
                enum:
                - error
              data:
                type: array
                items:
                  $ref: '#/components/schemas/resource_validation_result'
              error:
                type: string
                description: Error message
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - error
            properties:
              status:
                type: string
                enum:
                - error
              data:
                type: array
                items:
                  $ref: '#/components/schemas/resource_validation_result'
              error:
                type: string
                description: Error message
  securitySchemes:
    scmOAuth:
      type: oauth2
      description: "Strata Cloud Manager APIs authenticate client requests using the \nOAuth 2.0 Client Credentials flow.  Please use the `client_id`, \n`client_secret` values associated with an IAM service account along \nwith a scope value of `tsg_id:XXXXXXXXXX`, where `XXXXXXXXXX` is the \nTenant Service Group (TSG) ID.  The resulting JWT access token should \nbe attached to all API calls as a `Bearer` token in the `Authorization` \nheader (ex. `Authorization: Bearer tokenstring`).\n"
      flows:
        clientCredentials:
          tokenUrl: https://auth.apps.paloaltonetworks.com/oauth2/access_token
          scopes: {}
    scmToken:
      type: http
      description: "Strata Cloud Manager APIs authenticate client requests using the \nOAuth 2.0 Client Credentials flow.  Please use the `client_id`, \n`client_secret` values associated with an IAM service account along \nwith a scope value of `tsg_id:XXXXXXXXXX`, where `XXXXXXXXXX` is the \nTenant Service Group (TSG) ID.  The resulting JWT access token should \nbe attached to all API calls as a `Bearer` token in the `Authorization` \nheader (ex. `Authorization: Bearer tokenstring`).\n"
      scheme: bearer
      bearerFormat: JWT
x-internal: false