openapi: 3.2.0
info:
  title: Open API Spec Assurance Tasks API
  description: '### OpenAPI specification defined for the purpose of providing visibility into the status & lifecyle of asynchronous tasks/processes that are triggered within Assurance

    Task information is only persisted for 10 minutes. Historical information on tasks is not maintained after expiry.

    Submitted tasks have a timeout window of 5 minutes to complete a given operation.

    '
  termsOfService: https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html
  contact:
    name: Cisco TAC World Wide
    url: https://www.cisco.com/c/en/us/support/web/tsd-cisco-worldwide-contacts.html
    email: tac@cisco.com
  license:
    name: Cisco Catalyst Center License
    url: https://www.cisco.com/c/en/us/products/collateral/software/dna-software-ebook-cte.html
  version: 1.0.0
  x-provenance:
    method: harvested
    authored_by: Cisco Catalyst Center
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: developer.cisco.com
    note: 27 Cisco-published OpenAPI 3.0 Assurance documents (185 operations). Ownership confirmed from the tac@cisco.com contact, the Cisco EULA terms-of-service URL and the Cisco Catalyst Center license block carried in each document.
  x-evidence:
  - type: source
    url: https://developer.cisco.com/docs/catalyst-center/
  - type: source
    url: https://developer.cisco.com/dnacenter/
servers:
- url: https://developer.cisco.com/dna/data/api/v1
tags:
- name: assuranceTasks
  description: Operations related to retrieving information regarding assurance tasks
  externalDocs:
    description: Catalyst Center Assurance user guide
    url: https://www.cisco.com/c/en/us/support/cloud-systems-management/dna-center/products-user-guide-list.html
paths:
  /assuranceTasks:
    get:
      tags:
      - assuranceTasks
      summary: retrieve a list of assurance tasks
      description: 'returns all existing tasks in a paginated list


        default sorting of list is `startTime`, `asc`


        valid field to sort by are [`startTime`,`endTime`,`updateTime`,`status`]

        '
      operationId: readAssuranceTasks
      parameters:
      - name: limit
        in: query
        description: Maximum number of records to return
        schema:
          maximum: 500
          minimum: 1
          type: integer
          default: 500
      - name: offset
        in: query
        description: Specifies the starting point within all records returned by the API. It's one based offset. The starting value is 1.
        schema:
          minimum: 1
          type: integer
          default: 1
      - name: sortBy
        in: query
        description: A field within the response to sort by.
        schema:
          type: string
      - name: order
        in: query
        description: The sort order of the field ascending or descending.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: status
        in: query
        description: used to get a subset of tasks by their status
        schema:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILURE
      - name: X-CALLER-ID
        in: header
        description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request.

          '
        required: false
        schema:
          type: string
          default: unknown
        example: intent
      responses:
        '200':
          description: Assurance tasks response model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssuranceTasks'
              examples:
                list:
                  $ref: '#/components/examples/AssuranceTaskList'
        '500':
          description: The server could not fulfill the request due to internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        1XX:
          description: Informational Responses - The server received the request and sent an informational response.
        2XX:
          description: Successful Responses - The server received the client request, understood it, and accepted it.
        3XX:
          description: Redirection Messages - The client must take additional action to complete the request.
        4XX:
          description: Client Error Responses - The client request caused the error.
        5XX:
          description: Server Error Responses - The server failed to fulfill the request.
        default:
          description: Unexpected Error
  /assuranceTasks/{id}:
    get:
      tags:
      - assuranceTasks
      summary: retrieve a specific assurance task by id
      description: 'returns a task given a specific task id

        '
      operationId: readAssuranceTaskById
      parameters:
      - name: id
        in: path
        description: unique task id
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: X-CALLER-ID
        in: header
        description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request.

          '
        required: false
        schema:
          type: string
          default: unknown
        example: intent
      responses:
        '200':
          description: Assurance tasks info model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssuranceTaskInfo'
              examples:
                taskError:
                  $ref: '#/components/examples/AssuranceTaskErrorInfo'
                taskSuccess:
                  $ref: '#/components/examples/AssuranceTaskSuccessInfo'
                taskPending:
                  $ref: '#/components/examples/AssuranceTaskPendingInfo'
        '404':
          description: The client made a request for a resource that does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The server could not fulfill the request due to internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        1XX:
          description: Informational Responses - The server received the request and sent an informational response.
        2XX:
          description: Successful Responses - The server received the client request, understood it, and accepted it.
        3XX:
          description: Redirection Messages - The client must take additional action to complete the request.
        4XX:
          description: Client Error Responses - The client request caused the error.
        5XX:
          description: Server Error Responses - The server failed to fulfill the request.
        default:
          description: Unexpected Error
  /assuranceTasks/count:
    get:
      tags:
      - assuranceTasks
      summary: retrieve a count of the number of assurance tasks that currently exist
      description: 'returns a count of the number of assurance tasks that are not expired

        '
      operationId: readAssuranceTaskCount
      parameters:
      - name: X-CALLER-ID
        in: header
        description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request.

          '
        required: false
        schema:
          type: string
          default: unknown
        example: intent
      - name: status
        in: query
        description: used to get a subset of tasks by their status
        schema:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - FAILURE
      responses:
        '200':
          description: Successfully returned the total task count
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/CountIntegerResponse'
        '404':
          description: The client made a request for a resource that does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The server could not fulfill the request due to internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        1XX:
          description: Informational Responses - The server received the request and sent an informational response.
        2XX:
          description: Successful Responses - The server received the client request, understood it, and accepted it.
        3XX:
          description: Redirection Messages - The client must take additional action to complete the request.
        4XX:
          description: Client Error Responses - The client request caused the error.
        5XX:
          description: Server Error Responses - The server failed to fulfill the request.
        default:
          description: Unexpected Error
components:
  schemas:
    CountIntegerResponse:
      title: Count Integer Response
      type: object
      properties:
        response:
          $ref: '#/components/schemas/CountIntegerResponse_response'
        version:
          type: string
          description: The version of the response
          example: '1.0'
      description: Reports
    CountIntegerResponse_response:
      type: object
      properties:
        count:
          type: integer
          description: The total number of records related to the resource
          format: int64
          example: 1000
    ErrorResponse:
      title: Error Response
      type: object
      properties:
        response:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        version:
          type: string
          description: The version of the response
          example: '1.0'
      description: Contains information explaining the error that occured   processing this request.
      example:
        response:
        - errorCode: 2600
          message: Error message
          detail: Error details
      externalDocs:
        description: Error Codes - Cisco DevNet
        url: https://developer.cisco.com/docs/dna-center/#!api-quick-start/error-codes
    AssuranceTaskInfo:
      type: object
      properties:
        response:
          $ref: '#/components/schemas/AssuranceTask'
        version:
          type: string
          example: '1.0'
      description: Assurance Task Info
    AssuranceTask:
      type: object
      properties:
        id:
          type: string
          description: uuid of the submitted task/operation
          format: uuid
          example: bba22b5a-b9f6-4df1-8965-3fb076aaf802
        status:
          type: string
          description: the state of the submitted task/operation
          example: SUCCESS
          enum:
          - PENDING
          - FAILURE
          - SUCCESS
        startTime:
          type: integer
          description: the time the submitted task/operation started
          format: int64
          example: 1717955183000
        endTime:
          type: integer
          description: 'the time the submitted task/operation completed or failed


            tasks have a timeout window of 5 minutes

            '
          format: int64
          example: 1716213175000
        updateTime:
          type: integer
          description: the time the submitted task/operation was last updated
          format: int64
          example: 1716213175000
        progress:
          type: string
          description: optional string indicating progress made on task/operation
          example: process is completed
        failureReason:
          type: string
          description: information on why the task failed
          example: Internal exception hit while querying data
        errorCode:
          type: string
          description: optional string that could be used to expose relevant error codes related to failures
          example: '500'
        requestType:
          type: string
          description: optional string that can be used to provide information on the task's purpose
          example: SITE_QUERY_API
        data:
          type: object
          description: 'optional information indicating what data this operation is pertaining to.


            generally will be a JSON (API request body)


            but can also be a string depending on use case.

            '
        resultUrl:
          type: string
          description: in a success scenario, this will be the URL needed to retrieve the response data pertaining to the original request made
          example: /data/api/v1/siteHealthSummaries?taskId=ad2ebd0d-dd80-422e-8066-dc55c458e970
    ErrorObject:
      type: object
      properties:
        errorCode:
          type: integer
          description: Application specific error code returned by the server
        message:
          type: string
          description: Brief message about the error condition
        detail:
          type: string
          description: A more detailed explanation of the error condition the   parameter and its value, that caused the condition and why it caused it.
    PaginationResponse_sortBy:
      type: object
      properties:
        name:
          type: string
          description: Field name by which sort is requested
          example: siteHierarchy
        order:
          type: string
          description: Sort order. 'asc' for ascending and 'desc' for   descending
          example: asc
          enum:
          - asc
          - desc
      description: List of field names and corresponding order used to sort   the records.
    AssuranceTasks:
      type: object
      properties:
        response:
          type: array
          description: 'Successfully returned list of tasks

            '
          items:
            $ref: '#/components/schemas/AssuranceTask'
        page:
          $ref: '#/components/schemas/PaginationResponse'
        version:
          type: string
          example: '1.0'
      description: List of assurance tasks
    PaginationResponse:
      type: object
      properties:
        limit:
          type: integer
          description: The reference to the limit applied in the Pagination   Request.
          example: 10
        offset:
          type: integer
          description: The reference to the record offset applied in the   Pagination Request.
          example: 1
        count:
          type: integer
          description: Total number of records related to the resource after   applying applicable filtering
          example: 20
        sortBy:
          type: array
          description: Reference to the sortBy that was applied in the Pagination   Request.
          items:
            $ref: '#/components/schemas/PaginationResponse_sortBy'
  examples:
    AssuranceTaskErrorInfo:
      summary: Assurance Task that is in an error state
      value:
        response:
          id: bba22b5a-b9f6-4df1-8965-3fb076aaf802
          status: FAILURE
          startTime: 1717955183000
          endTime: 1716213175000
          updateTime: 1716213175000
          progress: Process has failed
          failureReason: An internal exception was hit while processing the request.
          errorCode: 500
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf802
        version: '1.0'
    AssuranceTaskList:
      value:
        response:
        - id: bba22b5a-b9f6-4df1-8965-3fb076aaf101
          status: FAILURE
          startTime: 1717955183000
          endTime: 1716213175000
          updateTime: 1716213175000
          progress: Process has failed
          failureReason: An internal exception was hit while processing the request.
          errorCode: 500
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf101
        - id: bba22b5a-b9f6-4df1-8965-3fb076aaf802
          status: SUCCESS
          startTime: 1717955183000
          endTime: 1716213175000
          updateTime: 1716213175000
          progress: Process has succeeded.
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf802
        - id: bba22b5a-b9f6-4df1-8965-3fb076aaf8101
          status: PENDING
          startTime: 1717955183000
          updateTime: 1716213175000
          progress: Querying data in progress.
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf8101
        page:
          limit: 3
          offset: 0
          count: 3
          sortBy:
          - name: startTime
            order: asc
        version: '1.0'
    AssuranceTaskSuccessInfo:
      summary: Assurance Task that is in an success state
      value:
        response:
          id: bba22b5a-b9f6-4df1-8965-3fb076aaf802
          status: SUCCESS
          startTime: 1717955183000
          endTime: 1716213175000
          updateTime: 1716213175000
          progress: Process has succeeded.
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf802
        version: '1.0'
    AssuranceTaskPendingInfo:
      summary: Assurance Task that is in an in pending state
      value:
        response:
          id: bba22b5a-b9f6-4df1-8965-3fb076aaf802
          status: PENDING
          startTime: 1717955183000
          updateTime: 1716213175000
          progress: Querying data in progress.
          requestType: SITE_QUERY_API
          data:
            startTime: 1718646534000
            endTime: 1718732934000
            attributes:
            - networkDeviceCount
            - clientCount
            filters:
            - key: networkDeviceCount
              operator: gt
              value: 10
            page:
              limit: 100
              offset: 5
              sortBy:
              - name: clientCount
                order: asc
          resultUrl: /data/api/v1/siteHealthSummaries?taskId=bba22b5a-b9f6-4df1-8965-3fb076aaf802
        version: '1.0'
externalDocs:
  description: Catalyst Center Developer API resources
  url: https://developer.cisco.com/dnacenter/