openapi: 3.0.3
info:
  title: Cumulocity Device Control API
  version: 10.20.0
  description: |
    Send and track operations (commands) to devices including firmware updates, configuration changes,
    software installation, shell commands, and restart requests. Operations move through PENDING, EXECUTING,
    SUCCESSFUL, FAILED status. Bulk operations let you target an entire device group with a single request.
servers:
- url: https://{tenant}.cumulocity.com
  variables:
    tenant:
      default: example
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Operations
- name: Bulk Operations
paths:
  /devicecontrol/operations:
    get:
      tags: [Operations]
      summary: List Operations
      operationId: listOperations
      parameters:
      - name: deviceId
        in: query
        schema: {type: string}
      - name: agentId
        in: query
        schema: {type: string}
      - name: status
        in: query
        schema:
          type: string
          enum: [PENDING, EXECUTING, SUCCESSFUL, FAILED]
      - name: fragmentType
        in: query
        schema: {type: string}
      - name: dateFrom
        in: query
        schema: {type: string, format: date-time}
      - name: dateTo
        in: query
        schema: {type: string, format: date-time}
      - name: revert
        in: query
        schema: {type: boolean}
      responses:
        '200':
          description: A collection of operations.
          content:
            application/vnd.com.nsn.cumulocity.operationCollection+json:
              schema:
                $ref: '#/components/schemas/OperationCollection'
    post:
      tags: [Operations]
      summary: Create an Operation
      operationId: createOperation
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.operation+json:
            schema:
              $ref: '#/components/schemas/Operation'
      responses:
        '201':
          description: Operation created.
    delete:
      tags: [Operations]
      summary: Delete Operations by Filter
      operationId: deleteOperations
      responses:
        '204':
          description: Operations deleted.
  /devicecontrol/operations/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Operations]
      summary: Retrieve an Operation
      operationId: getOperation
      responses:
        '200':
          description: A single operation.
          content:
            application/vnd.com.nsn.cumulocity.operation+json:
              schema:
                $ref: '#/components/schemas/Operation'
    put:
      tags: [Operations]
      summary: Update an Operation
      operationId: updateOperation
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.operation+json:
            schema:
              $ref: '#/components/schemas/Operation'
      responses:
        '200':
          description: Operation updated.
  /devicecontrol/bulkoperations:
    get:
      tags: [Bulk Operations]
      summary: List Bulk Operations
      operationId: listBulkOperations
      responses:
        '200':
          description: A collection of bulk operations.
    post:
      tags: [Bulk Operations]
      summary: Create a Bulk Operation
      operationId: createBulkOperation
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.bulkOperation+json:
            schema:
              $ref: '#/components/schemas/BulkOperation'
      responses:
        '201':
          description: Bulk operation created.
  /devicecontrol/bulkoperations/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Bulk Operations]
      summary: Retrieve a Bulk Operation
      operationId: getBulkOperation
      responses:
        '200':
          description: A single bulk operation.
    put:
      tags: [Bulk Operations]
      summary: Update a Bulk Operation
      operationId: updateBulkOperation
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.bulkOperation+json:
            schema:
              $ref: '#/components/schemas/BulkOperation'
      responses:
        '200':
          description: Bulk operation updated.
    delete:
      tags: [Bulk Operations]
      summary: Delete a Bulk Operation
      operationId: deleteBulkOperation
      responses:
        '204':
          description: Bulk operation deleted.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Operation:
      type: object
      required: [deviceId]
      properties:
        id: {type: string, readOnly: true}
        self: {type: string, format: uri, readOnly: true}
        deviceId: {type: string}
        deviceExternalIDs:
          type: object
        agentId: {type: string}
        status:
          type: string
          enum: [PENDING, EXECUTING, SUCCESSFUL, FAILED]
        creationTime: {type: string, format: date-time, readOnly: true}
        failureReason: {type: string}
        description: {type: string}
        c8y_Restart: {type: object}
        c8y_Command:
          type: object
          properties:
            text: {type: string}
            result: {type: string}
        c8y_Firmware:
          type: object
          properties:
            name: {type: string}
            version: {type: string}
            url: {type: string}
        c8y_Software:
          type: array
      additionalProperties: true
    OperationCollection:
      type: object
      properties:
        self: {type: string, format: uri}
        operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
    BulkOperation:
      type: object
      properties:
        id: {type: string, readOnly: true}
        groupId: {type: string}
        failedParentId: {type: string}
        startDate: {type: string, format: date-time}
        creationRamp: {type: integer}
        status:
          type: string
          enum: [ACTIVE, IN_PROGRESS, COMPLETED, CANCELED]
        operationPrototype:
          type: object
        progress:
          type: object
          properties:
            pending: {type: integer}
            executing: {type: integer}
            successful: {type: integer}
            failed: {type: integer}
            all: {type: integer}
      additionalProperties: true