openapi: 3.0.3
info:
  title: Boltic Workflow API
  description: >-
    The Boltic Workflow API enables programmatic creation, management, and
    execution of automation workflows. Workflows are visual, no-code automation
    sequences that connect triggers with actions across 500+ integrations.
    The API supports HTTP-triggered workflows with customizable responses,
    scheduled executions, and webhook-based triggers. Workflows can incorporate
    integration, transformation, and destination actions with support for
    multiple AI providers.
  version: 1.0.0
  contact:
    name: Boltic
    url: https://www.boltic.io
  license:
    name: Proprietary
    url: https://www.boltic.io/terms
servers:
  - url: https://api.boltic.io/v1
    description: Boltic Workflow API
security:
  - bearerAuth: []
tags:
  - name: Executions
    description: Track and manage workflow executions
  - name: Triggers
    description: Manage workflow triggers
  - name: Workflows
    description: Create and manage automation workflows
paths:
  /workflows:
    get:
      operationId: listWorkflows
      summary: Boltic List all workflows
      description: Retrieve a paginated list of all workflows in the workspace.
      tags:
        - Workflows
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive, draft]
      responses:
        '200':
          description: A list of workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkflow
      summary: Boltic Create a new workflow
      description: >-
        Create a new automation workflow with triggers, actions, and
        configuration.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowInput'
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
  /workflows/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Boltic Get a workflow by ID
      description: Retrieve the full configuration and status of a specific workflow.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateWorkflow
      summary: Boltic Update a workflow
      description: Update the configuration of an existing workflow.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowInput'
      responses:
        '200':
          description: Workflow updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
    delete:
      operationId: deleteWorkflow
      summary: Boltic Delete a workflow
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Workflow deleted
  /workflows/{workflowId}/execute:
    post:
      operationId: executeWorkflow
      summary: Boltic Execute a workflow
      description: >-
        Trigger immediate execution of a workflow. Supports synchronous
        execution that waits for the workflow to complete before returning
        a response.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: object
                  additionalProperties: true
                  description: Input data to pass to the workflow
                async:
                  type: boolean
                  default: false
                  description: Whether to execute asynchronously
      responses:
        '200':
          description: Workflow execution result (synchronous)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        '202':
          description: Workflow execution started (asynchronous)
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionId:
                    type: string
                  status:
                    type: string
                    enum: [queued]
  /workflows/{workflowId}/activate:
    post:
      operationId: activateWorkflow
      summary: Boltic Activate a workflow
      description: Enable a workflow so it responds to triggers.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workflow activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /workflows/{workflowId}/deactivate:
    post:
      operationId: deactivateWorkflow
      summary: Boltic Deactivate a workflow
      description: Disable a workflow so it stops responding to triggers.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workflow deactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /workflows/{workflowId}/executions:
    get:
      operationId: listExecutions
      summary: Boltic List workflow executions
      description: Retrieve execution history for a specific workflow.
      tags:
        - Executions
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [running, completed, failed, cancelled]
      responses:
        '200':
          description: A list of executions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Execution'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
  /executions/{executionId}:
    get:
      operationId: getExecution
      summary: Boltic Get execution details
      description: Retrieve details and results of a specific workflow execution.
      tags:
        - Executions
      parameters:
        - name: executionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Execution details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
  /executions/{executionId}/cancel:
    post:
      operationId: cancelExecution
      summary: Boltic Cancel an execution
      description: Cancel a running workflow execution.
      tags:
        - Executions
      parameters:
        - name: executionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Execution cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
  /triggers:
    get:
      operationId: listTriggers
      summary: Boltic List available triggers
      description: Retrieve a list of all available trigger types.
      tags:
        - Triggers
      responses:
        '200':
          description: A list of trigger types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trigger'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Workflow:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [active, inactive, draft]
        trigger:
          $ref: '#/components/schemas/Trigger'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/Node'
        tags:
          type: array
          items:
            type: string
        executionCount:
          type: integer
          description: Total number of times this workflow has been executed
        lastExecutedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    WorkflowInput:
      type: object
      required:
        - name
        - trigger
      properties:
        name:
          type: string
        description:
          type: string
        trigger:
          $ref: '#/components/schemas/TriggerInput'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/NodeInput'
        tags:
          type: array
          items:
            type: string
    Trigger:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - http
            - schedule
            - webhook
            - copilot
            - table-change
            - manual
        config:
          type: object
          additionalProperties: true
          description: Trigger-specific configuration
        methods:
          type: array
          items:
            type: string
            enum: [GET, POST, PUT, DELETE]
          description: HTTP methods for HTTP triggers
    TriggerInput:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [http, schedule, webhook, copilot, table-change, manual]
        config:
          type: object
          additionalProperties: true
        methods:
          type: array
          items:
            type: string
    Node:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - integration
            - transformation
            - destination
            - condition
            - loop
            - ai
        name:
          type: string
        integrationId:
          type: string
        config:
          type: object
          additionalProperties: true
        position:
          type: object
          properties:
            x:
              type: number
            y:
              type: number
        connections:
          type: array
          items:
            type: object
            properties:
              targetNodeId:
                type: string
              condition:
                type: string
    NodeInput:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
        name:
          type: string
        integrationId:
          type: string
        config:
          type: object
          additionalProperties: true
        position:
          type: object
          properties:
            x:
              type: number
            y:
              type: number
        connections:
          type: array
          items:
            type: object
            properties:
              targetNodeId:
                type: string
              condition:
                type: string
    Execution:
      type: object
      properties:
        id:
          type: string
        workflowId:
          type: string
        status:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        input:
          type: object
          additionalProperties: true
        output:
          type: object
          additionalProperties: true
        error:
          type: object
          properties:
            message:
              type: string
            nodeId:
              type: string
            code:
              type: string
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        duration:
          type: integer
          description: Execution duration in milliseconds
        nodeResults:
          type: array
          items:
            type: object
            properties:
              nodeId:
                type: string
              status:
                type: string
              output:
                type: object
                additionalProperties: true
              duration:
                type: integer
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'