ThingsBoard ota-package-controller API

openapi: 3.1.0
info:
  title: ThingsBoard Admin admin-controller ota-package-controller API
  description: 'ThingsBoard Admin API — subset of the ThingsBoard REST API (open-source IoT platform). Covers: Admin, Audit Log, Event, Usage Info, Queue, Queue Stats, Mail Config Template, Qr Code Settings, Job.'
  version: 4.3.0.3DEMO
  contact:
    name: ThingsBoard team
    url: https://thingsboard.io
    email: info@thingsboard.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://demo.thingsboard.io
  description: ThingsBoard Live Demo
- url: http://localhost:8080
  description: Local ThingsBoard server
tags:
- name: ota-package-controller
  description: Ota Package
paths:
  /api/otaPackage:
    post:
      tags:
      - ota-package-controller
      summary: Create or Update OTA Package Info (saveOtaPackageInfo)
      description: "Create or update the OTA Package Info. When creating OTA Package Info, platform generates OTA Package id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). The newly created OTA Package id will be present in the response. Specify existing OTA Package id to update the OTA Package Info. Referencing non-existing OTA Package Id will cause 'Not Found' error. \n\nOTA Package combination of the title with the version is unique in the scope of tenant. \n\nAvailable for users with 'TENANT_ADMIN' authority."
      operationId: saveOtaPackageInfo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveOtaPackageInfoRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtaPackageInfo'
  /api/otaPackage/{otaPackageId}:
    get:
      tags:
      - ota-package-controller
      summary: Get OTA Package (getOtaPackageById)
      description: "Fetch the OTA Package object based on the provided OTA Package Id. The server checks that the OTA Package is owned by the same tenant. OTA Package is a heavyweight object that includes main information about the OTA Package and also data. \n\nAvailable for users with 'TENANT_ADMIN' authority."
      operationId: getOtaPackageById
      parameters:
      - name: otaPackageId
        in: path
        description: A string value representing the ota package id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtaPackage'
    post:
      tags:
      - ota-package-controller
      summary: Save OTA Package Data (saveOtaPackageData)
      description: 'Update the OTA Package. Adds the date to the existing OTA Package Info


        Available for users with ''TENANT_ADMIN'' authority.'
      operationId: saveOtaPackageData
      parameters:
      - name: otaPackageId
        in: path
        description: A string value representing the ota package id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      - name: checksum
        in: query
        description: OTA Package checksum. For example, '0xd87f7e0c'
        required: false
        schema:
          type: string
      - name: checksumAlgorithm
        in: query
        description: OTA Package checksum algorithm.
        required: true
        schema:
          type: string
          enum:
          - MD5
          - SHA256
          - SHA384
          - SHA512
          - CRC32
          - MURMUR3_32
          - MURMUR3_128
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: OTA Package data.
              required:
              - file
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtaPackageInfo'
    delete:
      tags:
      - ota-package-controller
      summary: Delete OTA Package (deleteOtaPackage)
      description: 'Deletes the OTA Package. Referencing non-existing OTA Package Id will cause an error. Can''t delete the OTA Package if it is referenced by existing devices or device profile.


        Available for users with ''TENANT_ADMIN'' authority.'
      operationId: deleteOtaPackage
      parameters:
      - name: otaPackageId
        in: path
        description: A string value representing the ota package id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/otaPackages:
    get:
      tags:
      - ota-package-controller
      summary: Get OTA Package Infos (getOtaPackages)
      description: "Returns a page of OTA Package Info objects owned by tenant. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. OTA Package Info is a lightweight object that includes main information about the OTA Package excluding the heavyweight data. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
      operationId: getOtaPackages
      parameters:
      - name: pageSize
        in: query
        description: Maximum amount of entities in a one page
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Sequence number of page starting from 0
        required: true
        schema:
          type: integer
          format: int32
      - name: textSearch
        in: query
        description: The case insensitive 'substring' filter based on the ota package title.
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
          enum:
          - createdTime
          - type
          - title
          - version
          - tag
          - url
          - fileName
          - dataSize
          - checksum
      - name: sortOrder
        in: query
        description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDataOtaPackageInfo'
  /api/otaPackages/{deviceProfileId}/{type}:
    get:
      tags:
      - ota-package-controller
      summary: Get OTA Package Infos (getOtaPackages)
      description: "Returns a page of OTA Package Info objects owned by tenant. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. OTA Package Info is a lightweight object that includes main information about the OTA Package excluding the heavyweight data. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
      operationId: getOtaPackages_1
      parameters:
      - name: deviceProfileId
        in: path
        description: A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      - name: type
        in: path
        description: OTA Package type.
        required: true
        schema:
          type: string
          enum:
          - FIRMWARE
          - SOFTWARE
      - name: pageSize
        in: query
        description: Maximum amount of entities in a one page
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Sequence number of page starting from 0
        required: true
        schema:
          type: integer
          format: int32
      - name: textSearch
        in: query
        description: The case insensitive 'substring' filter based on the ota package title.
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
          enum:
          - createdTime
          - type
          - title
          - version
          - tag
          - url
          - fileName
          - dataSize
          - checksum
      - name: sortOrder
        in: query
        description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDataOtaPackageInfo'
  /api/otaPackage/{otaPackageId}/download:
    get:
      tags:
      - ota-package-controller
      summary: Download OTA Package (downloadOtaPackage)
      description: 'Download OTA Package based on the provided OTA Package Id.


        Available for users with ''TENANT_ADMIN'' authority.'
      operationId: downloadOtaPackage
      parameters:
      - name: otaPackageId
        in: path
        description: A string value representing the ota package id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                format: binary
  /api/otaPackage/info/{otaPackageId}:
    get:
      tags:
      - ota-package-controller
      summary: Get OTA Package Info (getOtaPackageInfoById)
      description: "Fetch the OTA Package Info object based on the provided OTA Package Id. OTA Package Info is a lightweight object that includes main information about the OTA Package excluding the heavyweight data. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
      operationId: getOtaPackageInfoById
      parameters:
      - name: otaPackageId
        in: path
        description: A string value representing the ota package id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtaPackageInfo'
components:
  schemas:
    JsonNode:
      description: A value representing the any type (object or primitive)
      examples:
      - {}
    DeviceProfileId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - DEVICE_PROFILE
          example: DEVICE_PROFILE
      required:
      - entityType
      - id
    OtaPackageInfo:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/OtaPackageId'
          description: JSON object with the ota package Id. Specify existing ota package Id to update the ota package. Referencing non-existing ota package id will cause error. Omit this field to create new ota package.
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the ota package creation, in milliseconds
          example: 1609459200000
          readOnly: true
        tenantId:
          $ref: '#/components/schemas/TenantId'
          description: JSON object with Tenant Id. Tenant Id of the ota package can't be changed.
          readOnly: true
        deviceProfileId:
          $ref: '#/components/schemas/DeviceProfileId'
          description: JSON object with Device Profile Id. Device Profile Id of the ota package can't be changed.
          readOnly: true
        type:
          type: string
          description: OTA Package type.
          enum:
          - FIRMWARE
          - SOFTWARE
          example: FIRMWARE
          readOnly: true
        title:
          type: string
          description: OTA Package title.
          example: fw
          readOnly: true
        version:
          type: string
          description: OTA Package version.
          example: 1.0
          readOnly: true
        tag:
          type: string
          description: OTA Package tag.
          example: fw_1.0
          readOnly: true
        url:
          type: string
          description: OTA Package url.
          example: http://thingsboard.org/fw/1
          readOnly: true
        hasData:
          type: boolean
          description: Indicates OTA Package 'has data'. Field is returned from DB ('true' if data exists or url is set).  If OTA Package 'has data' is 'false' we can not assign the OTA Package to the Device or Device Profile.
          example: true
          readOnly: true
        fileName:
          type: string
          description: OTA Package file name.
          example: fw_1.0
          readOnly: true
        contentType:
          type: string
          description: OTA Package content type.
          example: APPLICATION_OCTET_STREAM
          readOnly: true
        checksumAlgorithm:
          type: string
          description: OTA Package checksum algorithm.
          enum:
          - MD5
          - SHA256
          - SHA384
          - SHA512
          - CRC32
          - MURMUR3_32
          - MURMUR3_128
          example: CRC32
          readOnly: true
        checksum:
          type: string
          description: OTA Package checksum.
          example: '0xd87f7e0c'
          readOnly: true
        dataSize:
          type: integer
          format: int64
          description: OTA Package data size.
          example: 8
          readOnly: true
        name:
          type: string
          readOnly: true
        additionalInfo:
          $ref: '#/components/schemas/JsonNode'
          description: OTA Package description.
          example: Description for the OTA Package fw_1.0
    OtaPackage:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/OtaPackageId'
          description: JSON object with the ota package Id. Specify existing ota package Id to update the ota package. Referencing non-existing ota package id will cause error. Omit this field to create new ota package.
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the ota package creation, in milliseconds
          example: 1609459200000
          readOnly: true
        tenantId:
          $ref: '#/components/schemas/TenantId'
          description: JSON object with Tenant Id. Tenant Id of the ota package can't be changed.
          readOnly: true
        deviceProfileId:
          $ref: '#/components/schemas/DeviceProfileId'
          description: JSON object with Device Profile Id. Device Profile Id of the ota package can't be changed.
          readOnly: true
        type:
          type: string
          description: OTA Package type.
          enum:
          - FIRMWARE
          - SOFTWARE
          example: FIRMWARE
          readOnly: true
        title:
          type: string
          description: OTA Package title.
          example: fw
          readOnly: true
        version:
          type: string
          description: OTA Package version.
          example: 1.0
          readOnly: true
        tag:
          type: string
          description: OTA Package tag.
          example: fw_1.0
          readOnly: true
        url:
          type: string
          description: OTA Package url.
          example: http://thingsboard.org/fw/1
          readOnly: true
        hasData:
          type: boolean
          description: Indicates OTA Package 'has data'. Field is returned from DB ('true' if data exists or url is set).  If OTA Package 'has data' is 'false' we can not assign the OTA Package to the Device or Device Profile.
          example: true
          readOnly: true
        fileName:
          type: string
          description: OTA Package file name.
          example: fw_1.0
          readOnly: true
        contentType:
          type: string
          description: OTA Package content type.
          example: APPLICATION_OCTET_STREAM
          readOnly: true
        checksumAlgorithm:
          type: string
          description: OTA Package checksum algorithm.
          enum:
          - MD5
          - SHA256
          - SHA384
          - SHA512
          - CRC32
          - MURMUR3_32
          - MURMUR3_128
          example: CRC32
          readOnly: true
        checksum:
          type: string
          description: OTA Package checksum.
          example: '0xd87f7e0c'
          readOnly: true
        dataSize:
          type: integer
          format: int64
          description: OTA Package data size.
          example: 8
          readOnly: true
        data:
          type: object
          properties:
            short:
              type: integer
              format: int32
            char:
              type: string
            int:
              type: integer
              format: int32
            long:
              type: integer
              format: int64
            float:
              type: number
              format: float
            double:
              type: number
              format: double
            direct:
              type: boolean
            readOnly:
              type: boolean
        name:
          type: string
          readOnly: true
        additionalInfo:
          $ref: '#/components/schemas/JsonNode'
          description: OTA Package description.
          example: Description for the OTA Package fw_1.0
    SaveOtaPackageInfoRequest:
      type: object
      description: A JSON value representing the OTA Package.
      properties:
        id:
          $ref: '#/components/schemas/OtaPackageId'
          description: JSON object with the ota package Id. Specify existing ota package Id to update the ota package. Referencing non-existing ota package id will cause error. Omit this field to create new ota package.
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the ota package creation, in milliseconds
          example: 1609459200000
          readOnly: true
        tenantId:
          $ref: '#/components/schemas/TenantId'
          description: JSON object with Tenant Id. Tenant Id of the ota package can't be changed.
          readOnly: true
        deviceProfileId:
          $ref: '#/components/schemas/DeviceProfileId'
          description: JSON object with Device Profile Id. Device Profile Id of the ota package can't be changed.
          readOnly: true
        type:
          type: string
          description: OTA Package type.
          enum:
          - FIRMWARE
          - SOFTWARE
          example: FIRMWARE
          readOnly: true
        title:
          type: string
          description: OTA Package title.
          example: fw
          readOnly: true
        version:
          type: string
          description: OTA Package version.
          example: 1.0
          readOnly: true
        tag:
          type: string
          description: OTA Package tag.
          example: fw_1.0
          readOnly: true
        url:
          type: string
          description: OTA Package url.
          example: http://thingsboard.org/fw/1
          readOnly: true
        hasData:
          type: boolean
          description: Indicates OTA Package 'has data'. Field is returned from DB ('true' if data exists or url is set).  If OTA Package 'has data' is 'false' we can not assign the OTA Package to the Device or Device Profile.
          example: true
          readOnly: true
        fileName:
          type: string
          description: OTA Package file name.
          example: fw_1.0
          readOnly: true
        contentType:
          type: string
          description: OTA Package content type.
          example: APPLICATION_OCTET_STREAM
          readOnly: true
        checksumAlgorithm:
          type: string
          description: OTA Package checksum algorithm.
          enum:
          - MD5
          - SHA256
          - SHA384
          - SHA512
          - CRC32
          - MURMUR3_32
          - MURMUR3_128
          example: CRC32
          readOnly: true
        checksum:
          type: string
          description: OTA Package checksum.
          example: '0xd87f7e0c'
          readOnly: true
        dataSize:
          type: integer
          format: int64
          description: OTA Package data size.
          example: 8
          readOnly: true
        usesUrl:
          type: boolean
          description: Indicates OTA Package uses url. Should be 'true' if uses url or 'false' if will be used data.
          example: true
          readOnly: true
        name:
          type: string
          readOnly: true
        additionalInfo:
          $ref: '#/components/schemas/JsonNode'
          description: OTA Package description.
          example: Description for the OTA Package fw_1.0
    OtaPackageId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - OTA_PACKAGE
          example: OTA_PACKAGE
      required:
      - entityType
      - id
    TenantId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - TENANT
          example: TENANT
      required:
      - entityType
      - id
    PageDataOtaPackageInfo:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/OtaPackageInfo'
          readOnly: true
        totalPages:
          type: integer
          format: int32
          description: Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria
          readOnly: true
        totalElements:
          type: integer
          format: int64
          description: Total number of elements in all available pages
          readOnly: true
        hasNext:
          type: boolean
          description: '''false'' value indicates the end of the result set'
          readOnly: true
  securitySchemes:
    HTTP login form:
      type: http
      description: Enter Username / Password
      scheme: loginPassword
      bearerFormat: /api/auth/login|X-Authorization
    API key form:
      type: apiKey
      description: 'Enter the API key value with ''ApiKey'' prefix in format: **ApiKey <your_api_key_value>**


        Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**


        <br>**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.<br>

        '
      name: X-Authorization
      in: header