openapi: 3.1.0
info:
  title: Conductor OSS REST API
  description: >-
    The Conductor OSS REST API exposes the workflow orchestration engine's
    surface for managing workflow definitions, starting and querying workflow
    executions, handling tasks and workers, registering event handlers, and
    administering metadata. Conductor OSS is the Netflix-founded, Orkes-stewarded
    open source workflow and agentic AI orchestration platform.
  version: 3.x
  contact:
    name: Conductor OSS
    url: https://conductor-oss.org/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: '{baseUrl}/api'
    description: Conductor Server
    variables:
      baseUrl:
        default: http://localhost:8080
paths:
  /metadata/workflow:
    get:
      operationId: listWorkflowDefinitions
      summary: List workflow definitions
      description: Returns all registered workflow definitions.
      tags:
        - Metadata
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowDef'
    post:
      operationId: registerWorkflowDefinition
      summary: Register a workflow definition
      description: Registers a new workflow definition.
      tags:
        - Metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowDef'
      responses:
        '204':
          description: Workflow definition registered
    put:
      operationId: updateWorkflowDefinitions
      summary: Update workflow definitions
      description: Updates existing workflow definitions.
      tags:
        - Metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/WorkflowDef'
      responses:
        '204':
          description: Workflow definitions updated
  /metadata/workflow/{name}:
    get:
      operationId: getWorkflowDefinition
      summary: Get workflow definition
      description: Returns a specific workflow definition by name.
      tags:
        - Metadata
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDef'
    delete:
      operationId: deleteWorkflowDefinition
      summary: Delete a workflow definition
      description: Deletes a workflow definition by name and version.
      tags:
        - Metadata
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: query
          schema:
            type: integer
      responses:
        '204':
          description: Workflow definition deleted
  /metadata/taskdefs:
    get:
      operationId: listTaskDefinitions
      summary: List task definitions
      description: Returns all registered task definitions.
      tags:
        - Metadata
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskDef'
    post:
      operationId: registerTaskDefinitions
      summary: Register task definitions
      description: Registers new task definitions.
      tags:
        - Metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TaskDef'
      responses:
        '204':
          description: Task definitions registered
  /metadata/taskdefs/{taskType}:
    get:
      operationId: getTaskDefinition
      summary: Get task definition
      description: Returns a specific task definition by name.
      tags:
        - Metadata
      parameters:
        - name: taskType
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDef'
    delete:
      operationId: deleteTaskDefinition
      summary: Delete a task definition
      description: Deletes a task definition by name.
      tags:
        - Metadata
      parameters:
        - name: taskType
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Task definition deleted
  /workflow:
    post:
      operationId: startWorkflow
      summary: Start a workflow
      description: Starts a new workflow execution.
      tags:
        - Workflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartWorkflowRequest'
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: string
                description: Workflow ID
  /workflow/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Get workflow execution
      description: Returns the execution details of a specific workflow.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: includeTasks
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
    delete:
      operationId: terminateWorkflow
      summary: Terminate a workflow
      description: Terminates a running workflow execution.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: reason
          in: query
          schema:
            type: string
      responses:
        '204':
          description: Workflow terminated
  /workflow/{workflowId}/pause:
    put:
      operationId: pauseWorkflow
      summary: Pause a workflow
      description: Pauses a running workflow execution.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Workflow paused
  /workflow/{workflowId}/resume:
    put:
      operationId: resumeWorkflow
      summary: Resume a workflow
      description: Resumes a paused workflow execution.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Workflow resumed
  /workflow/{workflowId}/restart:
    post:
      operationId: restartWorkflow
      summary: Restart a workflow
      description: Restarts a completed or terminated workflow from the beginning.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: useLatestDefinitions
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Workflow restarted
  /workflow/{workflowId}/retry:
    post:
      operationId: retryWorkflow
      summary: Retry a workflow
      description: Retries a failed workflow from the last failed task.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: resumeSubworkflowTasks
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Workflow retried
  /workflow/{workflowId}/rerun:
    post:
      operationId: rerunWorkflow
      summary: Rerun a workflow
      description: Reruns a completed workflow from a specific task.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerunWorkflowRequest'
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: string
  /workflow/{workflowId}/skiptask/{taskReferenceName}:
    put:
      operationId: skipTask
      summary: Skip a task
      description: Skips a specific task in a running workflow.
      tags:
        - Workflow
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: taskReferenceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Task skipped
  /workflow/search:
    get:
      operationId: searchWorkflows
      summary: Search workflows
      description: Search for workflow executions based on query parameters.
      tags:
        - Workflow
      parameters:
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 100
        - name: sort
          in: query
          schema:
            type: string
        - name: freeText
          in: query
          schema:
            type: string
        - name: query
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /tasks/poll/{taskType}:
    get:
      operationId: pollTask
      summary: Poll for a task
      description: Polls for a task of a given type for a worker.
      tags:
        - Tasks
      parameters:
        - name: taskType
          in: path
          required: true
          schema:
            type: string
        - name: workerid
          in: query
          schema:
            type: string
        - name: domain
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/poll/batch/{taskType}:
    get:
      operationId: batchPollTasks
      summary: Batch poll for tasks
      description: Polls for multiple tasks of a given type.
      tags:
        - Tasks
      parameters:
        - name: taskType
          in: path
          required: true
          schema:
            type: string
        - name: workerid
          in: query
          schema:
            type: string
        - name: count
          in: query
          schema:
            type: integer
            default: 1
        - name: timeout
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
  /tasks:
    post:
      operationId: updateTask
      summary: Update task status
      description: Updates the status of a task with results.
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskResult'
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              schema:
                type: string
  /tasks/{taskId}:
    get:
      operationId: getTask
      summary: Get task details
      description: Returns details of a specific task.
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/queue/sizes:
    get:
      operationId: getTaskQueueSizes
      summary: Get task queue sizes
      description: Returns the sizes of task queues.
      tags:
        - Tasks
      parameters:
        - name: taskType
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
  /event:
    get:
      operationId: listEventHandlers
      summary: List event handlers
      description: Returns all registered event handlers.
      tags:
        - Events
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventHandler'
    post:
      operationId: createEventHandler
      summary: Create event handler
      description: Registers a new event handler.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '204':
          description: Event handler created
components:
  schemas:
    WorkflowDef:
      type: object
      required:
        - name
        - tasks
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: integer
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowTask'
        inputParameters:
          type: array
          items:
            type: string
        outputParameters:
          type: object
        schemaVersion:
          type: integer
        restartable:
          type: boolean
        workflowStatusListenerEnabled:
          type: boolean
        timeoutSeconds:
          type: integer
          format: int64
        timeoutPolicy:
          type: string
          enum:
            - TIME_OUT_WF
            - ALERT_ONLY
        failureWorkflow:
          type: string
        ownerEmail:
          type: string
    WorkflowTask:
      type: object
      required:
        - name
        - taskReferenceName
        - type
      properties:
        name:
          type: string
        taskReferenceName:
          type: string
        type:
          type: string
          enum:
            - SIMPLE
            - DYNAMIC
            - FORK_JOIN
            - FORK_JOIN_DYNAMIC
            - DECISION
            - SWITCH
            - JOIN
            - DO_WHILE
            - SUB_WORKFLOW
            - EVENT
            - WAIT
            - HUMAN
            - HTTP
            - INLINE
            - JSON_JQ_TRANSFORM
            - SET_VARIABLE
            - TERMINATE
        inputParameters:
          type: object
        dynamicTaskNameParam:
          type: string
        caseValueParam:
          type: string
        caseExpression:
          type: string
        decisionCases:
          type: object
        defaultCase:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowTask'
        forkTasks:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/WorkflowTask'
        joinOn:
          type: array
          items:
            type: string
        subWorkflowParam:
          type: object
        optional:
          type: boolean
        startDelay:
          type: integer
        retryCount:
          type: integer
    TaskDef:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        retryCount:
          type: integer
        timeoutSeconds:
          type: integer
          format: int64
        inputKeys:
          type: array
          items:
            type: string
        outputKeys:
          type: array
          items:
            type: string
        timeoutPolicy:
          type: string
          enum:
            - RETRY
            - TIME_OUT_WF
            - ALERT_ONLY
        retryLogic:
          type: string
          enum:
            - FIXED
            - EXPONENTIAL_BACKOFF
            - LINEAR_BACKOFF
        retryDelaySeconds:
          type: integer
        responseTimeoutSeconds:
          type: integer
          format: int64
        concurrentExecLimit:
          type: integer
        rateLimitPerFrequency:
          type: integer
        rateLimitFrequencyInSeconds:
          type: integer
        ownerEmail:
          type: string
        pollTimeoutSeconds:
          type: integer
    StartWorkflowRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        version:
          type: integer
        correlationId:
          type: string
        input:
          type: object
        taskToDomain:
          type: object
          additionalProperties:
            type: string
        externalInputPayloadStoragePath:
          type: string
        priority:
          type: integer
    Workflow:
      type: object
      properties:
        workflowId:
          type: string
        workflowName:
          type: string
        workflowVersion:
          type: integer
        correlationId:
          type: string
        status:
          type: string
          enum:
            - RUNNING
            - COMPLETED
            - FAILED
            - TIMED_OUT
            - TERMINATED
            - PAUSED
        input:
          type: object
        output:
          type: object
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        startTime:
          type: integer
          format: int64
        endTime:
          type: integer
          format: int64
        updateTime:
          type: integer
          format: int64
        reasonForIncompletion:
          type: string
        priority:
          type: integer
        failedReferenceTaskNames:
          type: array
          items:
            type: string
    Task:
      type: object
      properties:
        taskId:
          type: string
        taskType:
          type: string
        status:
          type: string
          enum:
            - IN_PROGRESS
            - COMPLETED
            - FAILED
            - TIMED_OUT
            - CANCELED
            - SCHEDULED
        referenceTaskName:
          type: string
        workflowInstanceId:
          type: string
        inputData:
          type: object
        outputData:
          type: object
        scheduledTime:
          type: integer
          format: int64
        startTime:
          type: integer
          format: int64
        endTime:
          type: integer
          format: int64
        retryCount:
          type: integer
        pollCount:
          type: integer
        callbackAfterSeconds:
          type: integer
          format: int64
        workerId:
          type: string
    TaskResult:
      type: object
      required:
        - workflowInstanceId
        - taskId
        - status
      properties:
        workflowInstanceId:
          type: string
        taskId:
          type: string
        status:
          type: string
          enum:
            - IN_PROGRESS
            - COMPLETED
            - FAILED
        outputData:
          type: object
        reasonForIncompletion:
          type: string
        callbackAfterSeconds:
          type: integer
          format: int64
        workerId:
          type: string
    RerunWorkflowRequest:
      type: object
      properties:
        reRunFromWorkflowId:
          type: string
        reRunFromTaskId:
          type: string
        workflowInput:
          type: object
        taskInput:
          type: object
        correlationId:
          type: string
    SearchResult:
      type: object
      properties:
        totalHits:
          type: integer
          format: int64
        results:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
    EventHandler:
      type: object
      properties:
        name:
          type: string
        event:
          type: string
        condition:
          type: string
        actions:
          type: array
          items:
            type: object
        active:
          type: boolean