Cisco Crosswork Cwztpdevice API

openapi: 3.2.0
info:
  title: proto/cw_ztp_device.proto Cwztpdevice API
  version: 2.0.0
  x-provenance:
    method: harvested
    authored_by: Cisco Crosswork
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
    provider_published: true
  x-evidence:
  - type: source
    url: https://github.com/CiscoDevNet/crosswork-openapi-spec/blob/master/ZTP/2.0APIs/cw_ztp_device.swagger.json
  - type: raw
    url: https://raw.githubusercontent.com/CiscoDevNet/crosswork-openapi-spec/master/ZTP/2.0APIs/cw_ztp_device.swagger.json
tags:
- name: cwztpdevice
paths:
  /v1/devices:
    delete:
      summary: Delete ZTP devices in bulk.
      operationId: DeleteDevice
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDeviceList'
        required: true
    post:
      summary: Add ZTP devices in bulk.
      operationId: SetDevices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDeviceList'
        required: true
    put:
      summary: Update a specified ZTP device when the device status is \"unprovisioned\" only.
      operationId: UpdateDevice
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevice'
        required: true
    patch:
      summary: Update a specified ZTP device when the device status is \"inprogress\"…
      operationId: UpdateDeviceStatus
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevice'
        required: true
  /v1/devices/csvtemplate:
    post:
      summary: Get the ZTP device headers with sample data in CSV format.
      operationId: ZtpsampleService
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevice'
        required: true
  /v1/devices/export:
    post:
      summary: Export the list of ZTP devices in CSV form.
      operationId: ExportDevice
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDeviceExportReq'
        required: true
  /v1/devices/import:
    post:
      summary: Add ZTP devices in bulk by importing a CSV file.
      operationId: ImportDevices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpImport'
        required: true
  /v1/devices/policies/query:
    post:
      summary: Retrieves a list of policies that apply on ZTP devices.
      operationId: GetDevicesPolicies
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDevicePolicyResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevicePolicyRequest'
        required: true
  /v1/devices/query:
    post:
      summary: Retrieves a list of ZTP devices.
      operationId: GetDevices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDeviceRequest'
        required: true
  /v1/onboarding:
    post:
      summary: Onboards a specified device from ZTP to Crosswork Device Lifecycle Management…
      operationId: OnboardDevice
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpDeviceResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevice'
        required: true
  /v1/query/count:
    post:
      summary: Get the total number of devices, profiles and devices with respective status.
      operationId: GetZtpCount
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cwztpsvcZtpCountResponse'
      tags:
      - cwztpdevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cwztpsvcZtpDevice'
        required: true
components:
  schemas:
    cwztpsvcProviderInfo:
      type: object
      properties:
        providerName:
          type: string
          title: The name of the Crosswork Provider. Should be unique
        providerDeviceKey:
          type: string
          title: Deprecated attribute from Crosswork 3.2.2 release
    cwztpsvcZtpDevicePolicyRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/cwztpsvcZtpDevicePolicy'
        filterData:
          $ref: '#/components/schemas/cwztpsvcZtpFilterData'
        criteria:
          type: string
        limit:
          type: integer
          format: int32
        page:
          type: integer
          format: int32
    cwztpsvcZtpDevice:
      type: object
      properties:
        uuid:
          type: string
          description: Unique device identifier. If a UUID is not passed, it is randomly generated by Crosswork.
        hostName:
          type: string
          description: The device Host name.
        serialNumber:
          type: array
          items:
            type: string
          description: The device Serial Number(s).
        credentialProfile:
          type: string
          title: 'REQUIRED: The name of the Credential Profile applicable to this device'
        ipAddress:
          $ref: '#/components/schemas/cwztpsvcZtpInetAddr'
          title: IP address od device
        macAddress:
          type: string
          description: The chassis backplane MAC address.
        osPlatform:
          type: string
          description: The OS Platform of the associated image and configuration file.
        version:
          type: string
          description: The Version of the associated image and configuration file.
        deviceFamily:
          type: string
          description: The Device Family of the associated image and configuration file.
        image:
          type: string
          description: The unique ID of the associated image file.
        config:
          type: string
          description: The unique ID of the associated day0-configuration file.
        profileName:
          type: string
          description: The name of the ZTP profile associated with the device.
        status:
          type: string
          title: The ZTP device status. Supported status values are \"Unprovisioned\", \"InProgress\", \"Provisioned\", \"ProvisioningError\", \"ZtpError\", \"Onboarded\", and \"OnboardingError\"
        providerInfo:
          $ref: '#/components/schemas/cwztpsvcProviderInfo'
          description: Data for the Crosswork Provider.
        connectivityDetails:
          type: array
          items:
            $ref: '#/components/schemas/cwztpsvcConnectivityDetail'
          description: List of device connectivity types.
        message:
          type: string
          description: Device onboarding status messages.
        lastUpdated:
          type: string
          format: int64
          title: TimeInMillis when device was last updated/created
        imageName:
          type: string
        configName:
          type: string
        isImageInvalid:
          type: boolean
          format: boolean
          description: Flag to check if the ZTP device is in sync with the associated image file.
        isConfigInvalid:
          type: boolean
          format: boolean
          description: Flag to check if the ZTP device is in sync with the associated configuration file.
        additionalAttributes:
          type: object
          additionalProperties:
            type: string
          description: A map of device attributes that are added as part of policy data.
        inventoryId:
          type: string
          description: Device Inventory ID. Supported starting with the Crosswork 3.2.2 release.
        isSecureZtp:
          type: string
          title: flag to identify if device is secure or classic
        secureZtpInfo:
          $ref: '#/components/schemas/cwztpsvcSecureZtpInfo'
          title: Secure ztp details
        configAttributes:
          type: object
          additionalProperties:
            type: string
          title: Extra config attributes from config script
        enableOption82:
          type: string
          title: Flag to identify if device is identified by location params or serial
        remoteId:
          type: string
          title: Location identifier params
        circuitId:
          type: string
    cwztpsvcZtpDeviceList:
      type: object
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/cwztpsvcZtpDevice'
    cwztpsvcConnectivityDetail:
      type: object
      properties:
        protocol:
          type: string
          description: The protocol for this connectivity type.
        inetAddr:
          type: array
          items:
            $ref: '#/components/schemas/cwztpsvcZtpInetAddr'
          description: The IPv4/IPv6 address for this connectivity type.
        port:
          type: integer
          format: int64
          description: The port for this connectivity type.
        timeout:
          type: integer
          format: int64
          description: The timeout for this connectivity type.
    cwztpsvcSecureZtpInfo:
      type: object
      properties:
        preConfig:
          type: string
          description: The unique ID of the associated pre-configuration file.
        postConfig:
          type: string
          description: The unique ID of the associated post-configuration file.
        preConfigName:
          type: string
        postConfigName:
          type: string
        isPreConfigInvalid:
          type: boolean
          format: boolean
          description: Flag to check if ZTP device is in sync with preConfigName.
        isPostConfigInvalid:
          type: boolean
          format: boolean
          description: Flag to check if ZTP device is in sync with postConfigName.
        isEncrypted:
          type: string
          description: Flag to check if ZTP device is data should be encrypted.
      title: Secure ZTP info
    cwztpsvcZtpDeviceRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/cwztpsvcZtpDevice'
        filterData:
          $ref: '#/components/schemas/cwztpsvcZtpFilterData'
        criteria:
          type: string
        limit:
          type: integer
          format: int32
        page:
          type: integer
          format: int32
    cwztpsvcZtpImport:
      type: object
      properties:
        b64Content:
          type: string
          title: encoded base64 content
        isDryRun:
          type: boolean
          format: boolean
          title: validate only device fields
    cwztpsvcZtpDeviceResponse:
      type: object
      properties:
        ztpnodes:
          type: array
          items:
            $ref: '#/components/schemas/cwztpsvcZtpDevice'
        code:
          type: integer
          format: int32
        message:
          type: string
        paginationDetails:
          $ref: '#/components/schemas/cwztpsvcZtpFilterData'
    cwztpsvcZtpFilterData:
      type: object
      properties:
        SortBy:
          type: string
        PageSize:
          type: integer
          format: int64
        PageNum:
          type: integer
          format: int64
        Descending:
          type: boolean
          format: boolean
        MatchCase:
          type: boolean
          format: boolean
        Criteria:
          type: string
        TotalCount:
          type: integer
          format: int64
    cwztpsvcZtpDevicePolicy:
      type: object
      properties:
        id:
          type: integer
          format: int32
          title: unique identifier
        policyFields:
          type: array
          items:
            type: string
          title: all the policy fields
        existingAttributes:
          type: object
          additionalProperties:
            type: string
          title: policy attributes that are exits in ztp
        newAttributes:
          type: object
          additionalProperties:
            type: string
          title: policy attributes that are added to ztp
    cwztpsvcZtpInetAddr:
      type: object
      properties:
        inetAddressFamily:
          type: string
        ipaddrs:
          type: string
        mask:
          type: integer
          format: int32
        type:
          type: string
      title: device ip address
    cwztpsvcZtpDevicePolicyResponse:
      type: object
      properties:
        policydata:
          $ref: '#/components/schemas/cwztpsvcZtpDevicePolicy'
        code:
          type: integer
          format: int32
        message:
          type: string
    cwztpsvcZtpCountResponse:
      type: object
      properties:
        totalprofilecount:
          type: integer
          format: int32
          description: Total number of ZTP profiles.
        totaldevicecount:
          type: integer
          format: int32
          description: Total number of ZTP devices.
        totalsztpdevicecount:
          type: integer
          format: int32
          description: Total number of secure ZTP devices.
        totalnonsztpdevicecount:
          type: integer
          format: int32
          description: Total number of non secure ZTP devices.
        statuscountmap:
          type: object
          additionalProperties:
            type: integer
            format: int32
          description: A map of status and respective count of devices.
        code:
          type: integer
          format: int32
      title: ZTP response for Device and Profile count
    cwztpsvcZtpDeviceExportReq:
      type: object
      properties:
        deviceId:
          type: array
          items:
            type: string