openapi: 3.1.0
info:
  title: Squillo Platform Connectors Workflows API
  description: The Squillo Platform API provides programmatic access to Squillo's Software as a Utility (SaaU) integration and automation platform. Enables management of workflows, connectors, integrations, triggers, and execution monitoring for IT process automation.
  version: '1.0'
  contact:
    name: Squillo Support
    url: https://squillo.io/
  license:
    name: Squillo Terms of Service
    url: https://squillo.io/
servers:
- url: https://api.squillo.io/v1
  description: Squillo Platform API
security:
- BearerAuth: []
tags:
- name: Workflows
  description: Workflow definition and management
paths:
  /workflows:
    get:
      operationId: listWorkflows
      summary: List Workflows
      description: Returns a list of all workflow definitions in the account, including their status, creation date, and trigger configuration.
      tags:
      - Workflows
      parameters:
      - name: status
        in: query
        description: Filter by workflow status
        schema:
          type: string
          enum:
          - active
          - inactive
          - draft
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      responses:
        '200':
          description: List of workflows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWorkflow
      summary: Create Workflow
      description: Creates a new workflow definition with specified steps, connectors, and trigger configuration.
      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':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workflows/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Get Workflow
      description: Returns the full definition for a specific workflow including all steps and configuration.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateWorkflow
      summary: Update Workflow
      description: Updates a workflow definition including steps, triggers, and configuration.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdate'
      responses:
        '200':
          description: Workflow updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
    delete:
      operationId: deleteWorkflow
      summary: Delete Workflow
      description: Permanently deletes a workflow definition and all associated execution history.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      responses:
        '204':
          description: Workflow deleted
  /workflows/{workflowId}/activate:
    post:
      operationId: activateWorkflow
      summary: Activate Workflow
      description: Activates a workflow, enabling its triggers to fire and accepting manual runs.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      responses:
        '200':
          description: Workflow activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /workflows/{workflowId}/deactivate:
    post:
      operationId: deactivateWorkflow
      summary: Deactivate Workflow
      description: Deactivates a workflow, preventing triggers from firing.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      responses:
        '200':
          description: Workflow deactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /workflows/{workflowId}/execute:
    post:
      operationId: executeWorkflow
      summary: Execute Workflow
      description: Manually triggers a workflow execution with optional input data. Returns the execution ID for monitoring.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/WorkflowId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                inputData:
                  type: object
                  description: Optional input payload for the workflow execution
      responses:
        '202':
          description: Execution started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
components:
  parameters:
    WorkflowId:
      name: workflowId
      in: path
      required: true
      description: Unique workflow identifier
      schema:
        type: string
  schemas:
    WorkflowUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        trigger:
          $ref: '#/components/schemas/Trigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
    Execution:
      type: object
      properties:
        id:
          type: string
        workflowId:
          type: string
        status:
          type: string
          enum:
          - running
          - success
          - failed
          - cancelled
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
        triggeredBy:
          type: string
          enum:
          - manual
          - schedule
          - webhook
          - event
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
    WorkflowListResponse:
      type: object
      properties:
        workflows:
          type: array
          items:
            $ref: '#/components/schemas/Workflow'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    Trigger:
      type: object
      properties:
        type:
          type: string
          enum:
          - webhook
          - schedule
          - manual
          - event
        config:
          type: object
          description: Trigger-specific configuration
    Workflow:
      type: object
      properties:
        id:
          type: string
          description: Unique workflow identifier
        name:
          type: string
          description: Human-readable workflow name
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
          - draft
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        trigger:
          $ref: '#/components/schemas/Trigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
        tags:
          type: array
          items:
            type: string
    WorkflowCreate:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        trigger:
          $ref: '#/components/schemas/Trigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
        tags:
          type: array
          items:
            type: string
    WorkflowStep:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - action
          - condition
          - loop
          - delay
          - transform
        connectorId:
          type: string
        action:
          type: string
        inputMapping:
          type: object
        outputMapping:
          type: object
        errorHandling:
          type: object
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT