openapi: 3.0.3
info:
  title: Talend Cloud Processing API
  description: >-
    The Talend Cloud Processing API manages task and plan executions, remote
    engine lifecycle, and run profiles in Qlik Talend Cloud. Use this API to
    trigger and monitor data integration job runs, manage remote engine clusters,
    and configure execution run profiles.
  version: 2021-03
  contact:
    name: Qlik Talend Support
    url: https://talend.qlik.dev
  termsOfService: https://www.qlik.com/us/legal/license-terms
externalDocs:
  description: Talend Processing API Documentation
  url: https://talend.qlik.dev/apis/processing/2021-03/
servers:
  - url: https://api.{region}.cloud.talend.com
    description: Talend Cloud API
    variables:
      region:
        description: Cloud region
        default: eu
        enum:
          - eu
          - us
          - us-west
          - ap
          - au
security:
  - BearerAuth: []
paths:
  /processing/executions:
    post:
      operationId: executeTask
      summary: Execute Task
      description: Trigger the execution of a data integration task
      tags:
        - Task Executions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskExecutionRequest'
      responses:
        '200':
          description: Task execution started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskExecution'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /processing/executions/{executionId}:
    get:
      operationId: getTaskExecutionStatus
      summary: Get Task Execution Status
      description: Check the status and details of a running or completed task execution
      tags:
        - Task Executions
      parameters:
        - $ref: '#/components/parameters/ExecutionId'
      responses:
        '200':
          description: Task execution details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskExecution'
    delete:
      operationId: terminateTaskExecution
      summary: Terminate Task Execution
      description: Stop a currently running task execution
      tags:
        - Task Executions
      parameters:
        - $ref: '#/components/parameters/ExecutionId'
      responses:
        '204':
          description: Execution terminated
  /processing/executables/tasks/executions:
    get:
      operationId: listTaskExecutions
      summary: List Task Executions
      description: Retrieve task execution history with optional filters
      tags:
        - Task Executions
      parameters:
        - name: taskId
          in: query
          schema:
            type: string
          description: Filter by task ID
        - name: status
          in: query
          schema:
            type: string
            enum:
              - RUNNING
              - SUCCESS
              - FAILURE
              - CANCELLED
          description: Filter by execution status
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of task executions
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskExecution'
    post:
      operationId: searchTaskExecutions
      summary: Search Task Executions
      description: Search task executions with advanced filters
      tags:
        - Task Executions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                taskId:
                  type: string
                status:
                  type: string
                startTime:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Search results
  /processing/executions/plans:
    post:
      operationId: executePlan
      summary: Execute Plan
      description: Trigger the execution of a data integration plan
      tags:
        - Plan Executions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanExecutionRequest'
      responses:
        '200':
          description: Plan execution started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanExecution'
  /processing/executions/plans/{planExecutionId}:
    get:
      operationId: getPlanExecutionStatus
      summary: Get Plan Execution Status
      description: Get detailed status of a plan execution
      tags:
        - Plan Executions
      parameters:
        - name: planExecutionId
          in: path
          required: true
          schema:
            type: string
          description: Plan execution identifier
      responses:
        '200':
          description: Plan execution status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanExecution'
  /processing/executions/plans/{planExecutionId}/steps:
    get:
      operationId: getPlanExecutionSteps
      summary: Get Plan Execution Steps
      description: Get the status of all step executions within a plan execution
      tags:
        - Plan Executions
      parameters:
        - name: planExecutionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plan execution steps
  /processing/runtimes/remote-engines:
    get:
      operationId: listRemoteEngines
      summary: List Remote Engines
      description: Get all available remote engines in the account
      tags:
        - Remote Engines
      responses:
        '200':
          description: List of remote engines
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RemoteEngine'
    post:
      operationId: createRemoteEngine
      summary: Create Remote Engine
      description: Register a new remote engine
      tags:
        - Remote Engines
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoteEngineCreate'
      responses:
        '201':
          description: Remote engine created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoteEngine'
  /processing/runtimes/remote-engines/{id}:
    get:
      operationId: getRemoteEngine
      summary: Get Remote Engine
      description: Retrieve details of a specific remote engine
      tags:
        - Remote Engines
      parameters:
        - $ref: '#/components/parameters/EngineId'
      responses:
        '200':
          description: Remote engine details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoteEngine'
    delete:
      operationId: deleteRemoteEngine
      summary: Delete Remote Engine
      description: Remove a remote engine from the account
      tags:
        - Remote Engines
      parameters:
        - $ref: '#/components/parameters/EngineId'
      responses:
        '204':
          description: Remote engine deleted
  /processing/runtimes/remote-engine-clusters:
    get:
      operationId: listRemoteEngineClusters
      summary: List Remote Engine Clusters
      description: Get all remote engine clusters in the account
      tags:
        - Remote Engine Clusters
      responses:
        '200':
          description: List of remote engine clusters
    post:
      operationId: createRemoteEngineCluster
      summary: Create Remote Engine Cluster
      description: Create a new remote engine cluster for load balancing
      tags:
        - Remote Engine Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: Cluster created
  /processing/run-profiles:
    post:
      operationId: createRunProfile
      summary: Create Run Profile
      description: Create a new run profile defining execution parameters
      tags:
        - Run Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunProfileCreate'
      responses:
        '201':
          description: Run profile created
  /processing/run-profiles/search:
    post:
      operationId: searchRunProfiles
      summary: Search Run Profiles
      description: Search run profiles with filters
      tags:
        - Run Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                engineId:
                  type: string
      responses:
        '200':
          description: Search results
  /processing/executables/plans/executions:
    get:
      operationId: listPlanExecutions
      summary: List Plan Executions
      description: Retrieve plan execution history
      tags:
        - Plan Executions
      parameters:
        - name: planId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - RUNNING
              - SUCCESS
              - FAILURE
              - CANCELLED
      responses:
        '200':
          description: List of plan executions
  /processing/executions/promotions:
    post:
      operationId: executePromotion
      summary: Execute Promotion
      description: Execute a promotion from source environment to target environment
      tags:
        - Promotion Executions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                promotionId:
                  type: string
                  description: The promotion to execute
      responses:
        '200':
          description: Promotion execution started
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token from Talend Cloud personal access token or service account token
  parameters:
    ExecutionId:
      name: executionId
      in: path
      required: true
      schema:
        type: string
      description: Execution identifier
    EngineId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Remote engine identifier
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing bearer token
    BadRequest:
      description: Bad Request - invalid request body
    NotFound:
      description: Not Found - resource does not exist
  schemas:
    TaskExecutionRequest:
      type: object
      required:
        - taskId
      properties:
        taskId:
          type: string
          description: Task identifier to execute
        environmentId:
          type: string
          description: Target execution environment
        logLevel:
          type: string
          enum:
            - INFO
            - DEBUG
            - TRACE
          description: Log verbosity level
    TaskExecution:
      type: object
      description: A task execution instance
      properties:
        executionId:
          type: string
          description: Unique execution identifier
        taskId:
          type: string
        status:
          type: string
          enum:
            - RUNNING
            - SUCCESS
            - FAILURE
            - CANCELLED
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        duration:
          type: integer
          description: Execution duration in milliseconds
        engineId:
          type: string
          description: Remote engine that ran the task
        logUrl:
          type: string
          format: uri
          description: URL to access execution logs
    PlanExecutionRequest:
      type: object
      required:
        - planId
      properties:
        planId:
          type: string
          description: Plan identifier to execute
        environmentId:
          type: string
        resumeFromStep:
          type: integer
          description: Step number to resume from (for re-runs after failure)
    PlanExecution:
      type: object
      description: A plan execution instance
      properties:
        executionId:
          type: string
        planId:
          type: string
        status:
          type: string
          enum:
            - RUNNING
            - SUCCESS
            - FAILURE
            - PARTIAL_SUCCESS
            - CANCELLED
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        steps:
          type: array
          items:
            type: object
            properties:
              stepId:
                type: string
              taskId:
                type: string
              status:
                type: string
              startTime:
                type: string
                format: date-time
              endTime:
                type: string
                format: date-time
    RemoteEngine:
      type: object
      description: A self-hosted Talend remote engine instance
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - PAIRED
            - UNPAIRED
            - OFFLINE
            - ONLINE
        version:
          type: string
          description: Talend Runtime version
        workspaceId:
          type: string
        created:
          type: string
          format: date-time
    RemoteEngineCreate:
      type: object
      required:
        - name
        - workspaceId
      properties:
        name:
          type: string
        workspaceId:
          type: string
        description:
          type: string
    RunProfileCreate:
      type: object
      required:
        - name
        - engineId
      properties:
        name:
          type: string
        engineId:
          type: string
        description:
          type: string
        parallelExecutions:
          type: integer
          description: Maximum concurrent executions