ThingsBoard job-controller API

openapi: 3.1.0
info:
  title: ThingsBoard Admin admin-controller job-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: job-controller
  description: Job
paths:
  /api/job/{id}/reprocess:
    post:
      tags:
      - job-controller
      operationId: reprocessJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
  /api/job/{id}/cancel:
    post:
      tags:
      - job-controller
      operationId: cancelJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
  /api/jobs:
    get:
      tags:
      - job-controller
      operationId: getJobs
      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: Case-insensitive 'substring' filter based on job's description
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
      - name: sortOrder
        in: query
        description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
        required: false
        schema:
          type: string
      - name: types
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - DUMMY
      - name: statuses
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - QUEUED
            - PENDING
            - RUNNING
            - COMPLETED
            - FAILED
            - CANCELLED
      - name: entities
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: startTime
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: endTime
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDataJob'
  /api/job/{id}:
    get:
      tags:
      - job-controller
      operationId: getJobById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
    delete:
      tags:
      - job-controller
      operationId: deleteJob
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
components:
  schemas:
    Job:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/JobId'
        createdTime:
          type: integer
          format: int64
          description: Entity creation timestamp in milliseconds since Unix epoch
          example: 1746028547220
          readOnly: true
        tenantId:
          $ref: '#/components/schemas/TenantId'
        type:
          type: string
          enum:
          - DUMMY
        key:
          type: string
          minLength: 1
        entityId:
          $ref: '#/components/schemas/EntityId'
        entityName:
          type: string
        status:
          type: string
          enum:
          - QUEUED
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELLED
        configuration:
          oneOf:
          - $ref: '#/components/schemas/DummyJobConfiguration'
        result:
          oneOf:
          - $ref: '#/components/schemas/DummyJobResult'
      required:
      - configuration
      - entityId
      - key
      - result
      - status
      - tenantId
      - type
    DummyTaskResult:
      allOf:
      - $ref: '#/components/schemas/TaskResult'
      - type: object
        properties:
          failure:
            $ref: '#/components/schemas/DummyTaskFailure'
    DummyTaskFailure:
      type: object
      properties:
        error:
          type: string
        number:
          type: integer
          format: int32
        failAlways:
          type: boolean
    PageDataJob:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/Job'
          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
    JobConfiguration:
      type: object
      discriminator:
        propertyName: type
      properties:
        tasksKey:
          type: string
          minLength: 1
        toReprocess:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/DummyTaskResult'
        type:
          type: string
      required:
      - tasksKey
      - type
    DummyJobResult:
      allOf:
      - $ref: '#/components/schemas/JobResult'
    JobResult:
      type: object
      discriminator:
        propertyName: jobType
      properties:
        successfulCount:
          type: integer
          format: int32
        failedCount:
          type: integer
          format: int32
        discardedCount:
          type: integer
          format: int32
        totalCount:
          type: integer
          format: int32
        results:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/DummyTaskResult'
        generalError:
          type: string
        startTs:
          type: integer
          format: int64
        finishTs:
          type: integer
          format: int64
        cancellationTs:
          type: integer
          format: int64
        jobType:
          type: string
      required:
      - jobType
    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
    TaskResult:
      type: object
      discriminator:
        propertyName: jobType
      properties:
        key:
          type: string
        success:
          type: boolean
        discarded:
          type: boolean
        finishTs:
          type: integer
          format: int64
        jobType:
          type: string
      required:
      - jobType
    JobId:
      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:
          - JOB
          example: JOB
      required:
      - entityType
      - id
    DummyJobConfiguration:
      allOf:
      - $ref: '#/components/schemas/JobConfiguration'
      - type: object
        properties:
          taskProcessingTimeMs:
            type: integer
            format: int64
          successfulTasksCount:
            type: integer
            format: int32
          failedTasksCount:
            type: integer
            format: int32
          permanentlyFailedTasksCount:
            type: integer
            format: int32
          errors:
            type: array
            items:
              type: string
          retries:
            type: integer
            format: int32
          taskProcessingTimeoutMs:
            type: integer
            format: int64
          generalError:
            type: string
          submittedTasksBeforeGeneralError:
            type: integer
            format: int32
      required:
      - tasksKey
    EntityId:
      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
          enum:
          - TENANT
          - CUSTOMER
          - USER
          - DASHBOARD
          - ASSET
          - DEVICE
          - ALARM
          - RULE_CHAIN
          - RULE_NODE
          - ENTITY_VIEW
          - WIDGETS_BUNDLE
          - WIDGET_TYPE
          - TENANT_PROFILE
          - DEVICE_PROFILE
          - ASSET_PROFILE
          - API_USAGE_STATE
          - TB_RESOURCE
          - OTA_PACKAGE
          - EDGE
          - RPC
          - QUEUE
          - NOTIFICATION_TARGET
          - NOTIFICATION_TEMPLATE
          - NOTIFICATION_REQUEST
          - NOTIFICATION
          - NOTIFICATION_RULE
          - QUEUE_STATS
          - OAUTH2_CLIENT
          - DOMAIN
          - MOBILE_APP
          - MOBILE_APP_BUNDLE
          - CALCULATED_FIELD
          - JOB
          - ADMIN_SETTINGS
          - AI_MODEL
          - API_KEY
          example: DEVICE
      required:
      - entityType
      - id
  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