openapi: 3.1.0
info:
  title: Xceptor Workflow API
  description: >-
    API for creating, managing, and executing data processing workflows
    within the Xceptor platform. Enables programmatic orchestration of
    automated data processing pipelines including event-driven triggers,
    business rules execution, step configuration, and workflow run monitoring.
    Workflows define multi-step processing sequences for enrichment,
    validation, reconciliation, and exception handling of financial data.
  version: '1.0'
  contact:
    name: Xceptor API Support
    url: https://www.xceptor.com/support
    email: api-support@xceptor.com
  termsOfService: https://www.xceptor.com/legal-tcs
externalDocs:
  description: Xceptor Workflow API Documentation
  url: https://docs.xceptor.com/api/workflows
servers:
  - url: https://api.xceptor.com/v1
    description: Production Server
tags:
  - name: Workflow Runs
    description: >-
      Operations for executing workflows, monitoring run status, and
      retrieving run history and output.
  - name: Workflow Steps
    description: >-
      Operations for managing the individual processing steps that compose
      a workflow, including step ordering and configuration.
  - name: Workflows
    description: >-
      Operations for creating, updating, listing, and deleting workflow
      definitions.
security:
  - bearerAuth: []
paths:
  /workflows:
    get:
      operationId: listWorkflows
      summary: Xceptor List Workflows
      description: >-
        Retrieves a paginated list of workflow definitions configured in the
        Xceptor platform. Workflows can be filtered by status, category, and
        name. Each workflow defines a multi-step data processing pipeline.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: status
          in: query
          description: Filter workflows by their activation status
          schema:
            type: string
            enum:
              - active
              - inactive
              - draft
        - name: category
          in: query
          description: Filter workflows by category
          schema:
            type: string
        - name: search
          in: query
          description: Search workflows by name or description
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of workflows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createWorkflow
      summary: Xceptor Create Workflow
      description: >-
        Creates a new workflow definition in the Xceptor platform. A workflow
        defines a sequence of processing steps that are executed in order to
        transform, validate, enrich, and route data through the automation
        pipeline.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCreate'
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Xceptor Get Workflow Details
      description: >-
        Retrieves the full definition of a specific workflow, including its
        steps, trigger configuration, and associated metadata.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateWorkflow
      summary: Xceptor Update Workflow
      description: >-
        Updates an existing workflow definition. Changes to active workflows
        take effect on subsequent runs. Running instances continue to use
        the previous version until completion.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdate'
      responses:
        '200':
          description: Workflow updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWorkflow
      summary: Xceptor Delete Workflow
      description: >-
        Deletes a workflow definition. Active workflows must be deactivated
        before deletion. Any running instances will complete before the
        workflow is removed.
      tags:
        - Workflows
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '204':
          description: Workflow deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/runs:
    get:
      operationId: listWorkflowRuns
      summary: Xceptor List Workflow Runs
      description: >-
        Retrieves a paginated list of execution runs for a specific workflow.
        Each run represents a single execution of the workflow and includes
        status, timing, and output information.
      tags:
        - Workflow Runs
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: status
          in: query
          description: Filter runs by execution status
          schema:
            type: string
            enum:
              - pending
              - running
              - completed
              - failed
              - cancelled
      responses:
        '200':
          description: A paginated list of workflow runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: executeWorkflow
      summary: Xceptor Execute Workflow
      description: >-
        Triggers an execution run of the specified workflow. The workflow
        is executed asynchronously and the run status can be monitored
        using the run details endpoint. Input parameters can be provided
        to configure the execution context.
      tags:
        - Workflow Runs
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunCreate'
      responses:
        '201':
          description: Workflow run initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '400':
          description: Invalid request body or workflow is not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/runs/{runId}:
    get:
      operationId: getWorkflowRun
      summary: Xceptor Get Workflow Run Details
      description: >-
        Retrieves the details and current status of a specific workflow run,
        including step-level progress, timing information, any errors
        encountered, and output references.
      tags:
        - Workflow Runs
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
        - $ref: '#/components/parameters/RunIdParam'
      responses:
        '200':
          description: Workflow run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow or run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: cancelWorkflowRun
      summary: Xceptor Cancel Workflow Run
      description: >-
        Cancels a pending or running workflow execution. The cancellation is
        asynchronous and the run status will transition to cancelled once
        all active steps have stopped processing.
      tags:
        - Workflow Runs
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
        - $ref: '#/components/parameters/RunIdParam'
      responses:
        '200':
          description: Workflow run cancellation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow or run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/steps:
    get:
      operationId: listWorkflowSteps
      summary: Xceptor List Workflow Steps
      description: >-
        Retrieves the ordered list of processing steps that compose a
        workflow. Each step represents a distinct processing operation such
        as extraction, transformation, validation, enrichment, or routing.
      tags:
        - Workflow Steps
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      responses:
        '200':
          description: A list of workflow steps
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowStep'
                    description: The ordered list of workflow steps
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: addWorkflowStep
      summary: Xceptor Add Workflow Step
      description: >-
        Adds a new processing step to a workflow. The step is inserted at the
        specified position in the workflow sequence. Steps can be configured
        with type-specific parameters for extraction, transformation,
        validation, and other operations.
      tags:
        - Workflow Steps
      parameters:
        - $ref: '#/components/parameters/WorkflowIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowStepCreate'
      responses:
        '201':
          description: Step added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStep'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth2 access token obtained via the client credentials flow.
        Include as a Bearer token in the Authorization header.
  parameters:
    WorkflowIdParam:
      name: workflowId
      in: path
      required: true
      description: The unique identifier of the workflow
      schema:
        type: string
        format: uuid
    RunIdParam:
      name: runId
      in: path
      required: true
      description: The unique identifier of the workflow run
      schema:
        type: string
        format: uuid
    PageParam:
      name: page
      in: query
      description: The page number for pagination (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSizeParam:
      name: page_size
      in: query
      description: The number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    Workflow:
      type: object
      description: >-
        A workflow definition that describes a multi-step data processing
        pipeline in the Xceptor platform.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the workflow
        name:
          type: string
          description: The display name of the workflow
        description:
          type: string
          description: A detailed description of what the workflow does
        status:
          type: string
          description: The activation status of the workflow
          enum:
            - active
            - inactive
            - draft
        category:
          type: string
          description: The category or group the workflow belongs to
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
            - manual
            - scheduled
            - event
            - api
        schedule:
          type: string
          description: >-
            The cron expression for scheduled workflows, applicable when
            trigger_type is scheduled
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
          description: The ordered list of processing steps in the workflow
        created_at:
          type: string
          format: date-time
          description: The date and time the workflow was created
        updated_at:
          type: string
          format: date-time
          description: The date and time the workflow was last updated
        created_by:
          type: string
          description: The identifier of the user who created the workflow
    WorkflowCreate:
      type: object
      description: Request body for creating a new workflow
      required:
        - name
        - trigger_type
      properties:
        name:
          type: string
          description: The display name of the workflow
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: A detailed description of what the workflow does
          maxLength: 2000
        category:
          type: string
          description: The category or group for the workflow
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
            - manual
            - scheduled
            - event
            - api
        schedule:
          type: string
          description: >-
            Cron expression for scheduled workflows. Required when
            trigger_type is scheduled.
    WorkflowUpdate:
      type: object
      description: Request body for updating an existing workflow
      properties:
        name:
          type: string
          description: The display name of the workflow
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: A detailed description of what the workflow does
          maxLength: 2000
        status:
          type: string
          description: The activation status of the workflow
          enum:
            - active
            - inactive
            - draft
        category:
          type: string
          description: The category or group for the workflow
        trigger_type:
          type: string
          description: How the workflow is triggered for execution
          enum:
            - manual
            - scheduled
            - event
            - api
        schedule:
          type: string
          description: >-
            Cron expression for scheduled workflows. Required when
            trigger_type is scheduled.
    WorkflowList:
      type: object
      description: A paginated list of workflows
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
          description: The list of workflows for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    WorkflowStep:
      type: object
      description: >-
        A single processing step within a workflow. Steps are executed in
        sequence and each performs a specific data processing operation.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the step
        name:
          type: string
          description: The display name of the step
        type:
          type: string
          description: The type of processing operation the step performs
          enum:
            - extraction
            - transformation
            - validation
            - enrichment
            - routing
            - notification
            - export
            - custom
        position:
          type: integer
          description: The position of the step in the workflow sequence (0-based)
          minimum: 0
        configuration:
          type: object
          description: Type-specific configuration parameters for the step
          additionalProperties: true
        enabled:
          type: boolean
          description: Whether the step is enabled for execution
          default: true
    WorkflowStepCreate:
      type: object
      description: Request body for adding a new step to a workflow
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: The display name of the step
          minLength: 1
          maxLength: 255
        type:
          type: string
          description: The type of processing operation
          enum:
            - extraction
            - transformation
            - validation
            - enrichment
            - routing
            - notification
            - export
            - custom
        position:
          type: integer
          description: >-
            The desired position in the workflow sequence. If omitted, the
            step is appended to the end.
          minimum: 0
        configuration:
          type: object
          description: Type-specific configuration parameters for the step
          additionalProperties: true
        enabled:
          type: boolean
          description: Whether the step is enabled for execution
          default: true
    WorkflowRun:
      type: object
      description: >-
        A single execution instance of a workflow. Tracks the progress and
        outcome of running a workflow's processing pipeline.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the run
        workflow_id:
          type: string
          format: uuid
          description: The identifier of the workflow that was executed
        status:
          type: string
          description: The current execution status of the run
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
        triggered_by:
          type: string
          description: How this run was triggered
          enum:
            - manual
            - schedule
            - event
            - api
        started_at:
          type: string
          format: date-time
          description: The date and time the run started executing
        completed_at:
          type: string
          format: date-time
          description: The date and time the run completed
        duration_ms:
          type: integer
          description: The total run duration in milliseconds
          minimum: 0
        step_results:
          type: array
          items:
            $ref: '#/components/schemas/StepResult'
          description: The results of each step in the workflow run
        input_parameters:
          type: object
          description: The input parameters provided for this run
          additionalProperties: true
        error:
          $ref: '#/components/schemas/Error'
    WorkflowRunCreate:
      type: object
      description: Request body for triggering a workflow execution
      properties:
        parameters:
          type: object
          description: Input parameters for the workflow execution
          additionalProperties: true
    WorkflowRunList:
      type: object
      description: A paginated list of workflow runs
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRun'
          description: The list of workflow runs for the current page
        pagination:
          $ref: '#/components/schemas/Pagination'
    StepResult:
      type: object
      description: The result of executing a single workflow step
      properties:
        step_id:
          type: string
          format: uuid
          description: The identifier of the workflow step
        step_name:
          type: string
          description: The name of the workflow step
        status:
          type: string
          description: The execution status of the step
          enum:
            - pending
            - running
            - completed
            - failed
            - skipped
        started_at:
          type: string
          format: date-time
          description: The date and time the step started
        completed_at:
          type: string
          format: date-time
          description: The date and time the step completed
        records_processed:
          type: integer
          description: The number of data records processed by the step
          minimum: 0
        records_failed:
          type: integer
          description: The number of records that failed processing
          minimum: 0
        error:
          $ref: '#/components/schemas/Error'
    Pagination:
      type: object
      description: Pagination information for list responses
      properties:
        page:
          type: integer
          description: The current page number
        page_size:
          type: integer
          description: The number of items per page
        total_items:
          type: integer
          description: The total number of items across all pages
        total_pages:
          type: integer
          description: The total number of pages
    Error:
      type: object
      description: An error response from the Xceptor API
      properties:
        code:
          type: string
          description: A machine-readable error code
        message:
          type: string
          description: A human-readable description of the error
        details:
          type: object
          description: Additional error details when available
          additionalProperties: true