openapi: 3.0.3
info:
  title: Alloy Automation Embedded API
  description: >-
    The Alloy Embedded API enables SaaS companies to embed native integration
    workflows directly in their products. Manage end users, retrieve available
    integrations, trigger events, monitor workflow execution, and control workflow
    lifecycle for your embedded iPaaS experience.
  version: 2025-09
  contact:
    name: Alloy Automation Support
    url: https://runalloy.com/
  x-generated-from: documentation
servers:
  - url: https://embedded.runalloy.com/2025-09
    description: Alloy Embedded API production server
security:
  - ApiKey: []
tags:
  - name: Users
    description: End user management for embedded integrations
  - name: Integrations
    description: Available integration catalog operations
  - name: Workflows
    description: Workflow lifecycle and monitoring operations
  - name: Events
    description: Custom event triggering operations
paths:
  /users:
    post:
      operationId: createUser
      summary: Alloy Create User
      description: Create a new end user in the Alloy Embedded platform to manage their integrations and credentials.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              CreateUserRequestExample:
                summary: Default createUser request
                x-microcks-default: true
                value:
                  username: "user-123"
                  fullName: "Jane Smith"
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                CreateUser201Example:
                  summary: Default createUser 201 response
                  x-microcks-default: true
                  value:
                    userId: "usr_abc123"
                    username: "user-123"
                    fullName: "Jane Smith"
                    createdAt: "2026-04-19T10:00:00Z"
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /users/{userId}/token:
    get:
      operationId: generateUserToken
      summary: Alloy Generate User Token
      description: Generate a short-lived JSON Web Token (JWT) for an end user to authenticate frontend SDK operations.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: The unique identifier of the user
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: JWT token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                GenerateUserToken200Example:
                  summary: Default generateUserToken 200 response
                  x-microcks-default: true
                  value:
                    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /users/{userId}/logs:
    delete:
      operationId: deleteUserLogs
      summary: Alloy Delete User Logs
      description: Purge all workflow execution logs and user-related data for GDPR/CCPA compliance.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: The unique identifier of the user
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: User logs deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                DeleteUserLogs200Example:
                  summary: Default deleteUserLogs 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: "User logs purged successfully"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /integrations:
    get:
      operationId: listIntegrations
      summary: Alloy List Integrations
      description: Retrieve available integrations for a user, including metadata such as connector icons and categories.
      tags:
        - Integrations
      parameters:
        - name: userId
          in: query
          required: true
          description: Filter integrations by user identifier
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: Integrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationList'
              examples:
                ListIntegrations200Example:
                  summary: Default listIntegrations 200 response
                  x-microcks-default: true
                  value:
                    integrations:
                      - integrationId: "int_shopify"
                        name: "Shopify"
                        category: "E-Commerce"
                        iconUrl: "https://assets.runalloy.com/icons/shopify.png"
                        installed: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /run/event:
    post:
      operationId: triggerEvent
      summary: Alloy Trigger Event
      description: Trigger a custom event to start or resume workflow execution for a user.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerEventRequest'
            examples:
              TriggerEventRequestExample:
                summary: Default triggerEvent request
                x-microcks-default: true
                value:
                  userId: "usr_abc123"
                  event: "order.created"
                  data:
                    orderId: "ord-789"
                    amount: 150.00
      responses:
        '200':
          description: Event triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                TriggerEvent200Example:
                  summary: Default triggerEvent 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: "Event triggered successfully"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /workflows/{workflowId}/errors:
    get:
      operationId: listWorkflowErrors
      summary: Alloy List Workflow Errors
      description: Retrieve workflow error logs for a specific workflow to debug integration failures.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          description: Unique identifier of the workflow
          schema:
            type: string
          example: "wf_xyz456"
        - name: userId
          in: query
          required: true
          description: Filter errors by user identifier
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: Workflow errors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorList'
              examples:
                ListWorkflowErrors200Example:
                  summary: Default listWorkflowErrors 200 response
                  x-microcks-default: true
                  value:
                    errors:
                      - errorId: "err_001"
                        workflowId: "wf_xyz456"
                        message: "Connection timeout to Shopify"
                        occurredAt: "2026-04-19T09:30:00Z"
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /workflows/{workflowId}/logs:
    get:
      operationId: listWorkflowLogs
      summary: Alloy List Workflow Logs
      description: Retrieve historical workflow execution logs for monitoring and debugging.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          description: Unique identifier of the workflow
          schema:
            type: string
          example: "wf_xyz456"
        - name: userId
          in: query
          required: true
          description: Filter logs by user identifier
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: Workflow logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowLogList'
              examples:
                ListWorkflowLogs200Example:
                  summary: Default listWorkflowLogs 200 response
                  x-microcks-default: true
                  value:
                    logs:
                      - logId: "log_001"
                        workflowId: "wf_xyz456"
                        status: success
                        executedAt: "2026-04-19T10:00:00Z"
                        duration: 1200
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /workflows/deactivate:
    put:
      operationId: deactivateWorkflow
      summary: Alloy Deactivate Workflow
      description: Disable an installed workflow for a user, pausing all automated executions.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowActionRequest'
            examples:
              DeactivateWorkflowExample:
                summary: Default deactivateWorkflow request
                x-microcks-default: true
                value:
                  workflowId: "wf_xyz456"
                  userId: "usr_abc123"
      responses:
        '200':
          description: Workflow deactivated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                DeactivateWorkflow200Example:
                  summary: Default deactivateWorkflow 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: "Workflow deactivated"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /workflows/activate:
    put:
      operationId: activateWorkflow
      summary: Alloy Activate Workflow
      description: Re-enable a deactivated workflow for a user, resuming automated executions.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowActionRequest'
            examples:
              ActivateWorkflowExample:
                summary: Default activateWorkflow request
                x-microcks-default: true
                value:
                  workflowId: "wf_xyz456"
                  userId: "usr_abc123"
      responses:
        '200':
          description: Workflow activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                ActivateWorkflow200Example:
                  summary: Default activateWorkflow 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: "Workflow activated"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /workflows/{workflowId}/upgrade:
    put:
      operationId: upgradeWorkflow
      summary: Alloy Upgrade Workflow
      description: Update a user's installed workflow to a newer version with the latest integration logic.
      tags:
        - Workflows
      parameters:
        - name: workflowId
          in: path
          required: true
          description: Unique identifier of the workflow to upgrade
          schema:
            type: string
          example: "wf_xyz456"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeWorkflowRequest'
            examples:
              UpgradeWorkflowExample:
                summary: Default upgradeWorkflow request
                x-microcks-default: true
                value:
                  userId: "usr_abc123"
                  version: "2.0.0"
      responses:
        '200':
          description: Workflow upgraded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                UpgradeWorkflow200Example:
                  summary: Default upgradeWorkflow 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: "Workflow upgraded to version 2.0.0"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: API key in Authorization header (bearer YOUR_API_KEY)

  schemas:
    User:
      title: User
      type: object
      description: An end user in the Alloy Embedded platform
      properties:
        userId:
          type: string
          description: Unique identifier for the user
          example: "usr_abc123"
        username:
          type: string
          description: Username or external identifier for the user
          example: "user-123"
        fullName:
          type: string
          description: Full display name of the user
          example: "Jane Smith"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user was created
          example: "2026-04-19T10:00:00Z"

    CreateUserRequest:
      title: CreateUserRequest
      type: object
      description: Request body for creating a new end user
      required:
        - username
      properties:
        username:
          type: string
          description: Unique username or external identifier
          example: "user-123"
        fullName:
          type: string
          description: Full display name of the user
          example: "Jane Smith"

    TokenResponse:
      title: TokenResponse
      type: object
      description: JWT token response for user authentication
      properties:
        token:
          type: string
          description: Short-lived JSON Web Token for frontend SDK authentication
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"

    Integration:
      title: Integration
      type: object
      description: An available integration in the Alloy catalog
      properties:
        integrationId:
          type: string
          description: Unique identifier for the integration
          example: "int_shopify"
        name:
          type: string
          description: Display name of the integration
          example: "Shopify"
        category:
          type: string
          description: Integration category
          example: "E-Commerce"
        iconUrl:
          type: string
          format: uri
          description: URL to the integration icon
          example: "https://assets.runalloy.com/icons/shopify.png"
        installed:
          type: boolean
          description: Whether the integration is installed for the user
          example: false

    IntegrationList:
      title: IntegrationList
      type: object
      description: List of available integrations
      properties:
        integrations:
          type: array
          description: List of integration records
          items:
            $ref: '#/components/schemas/Integration'

    TriggerEventRequest:
      title: TriggerEventRequest
      type: object
      description: Request body for triggering a custom workflow event
      required:
        - userId
        - event
      properties:
        userId:
          type: string
          description: Identifier of the user triggering the event
          example: "usr_abc123"
        event:
          type: string
          description: Event name to trigger
          example: "order.created"
        data:
          type: object
          description: Event payload data
          example:
            orderId: "ord-789"
            amount: 150.00

    WorkflowError:
      title: WorkflowError
      type: object
      description: A workflow execution error record
      properties:
        errorId:
          type: string
          description: Unique identifier for the error
          example: "err_001"
        workflowId:
          type: string
          description: Workflow identifier where the error occurred
          example: "wf_xyz456"
        message:
          type: string
          description: Human-readable error description
          example: "Connection timeout to Shopify"
        occurredAt:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: "2026-04-19T09:30:00Z"

    WorkflowErrorList:
      title: WorkflowErrorList
      type: object
      description: List of workflow execution errors
      properties:
        errors:
          type: array
          description: List of error records
          items:
            $ref: '#/components/schemas/WorkflowError'

    WorkflowLog:
      title: WorkflowLog
      type: object
      description: A workflow execution log entry
      properties:
        logId:
          type: string
          description: Unique identifier for the log entry
          example: "log_001"
        workflowId:
          type: string
          description: Workflow identifier
          example: "wf_xyz456"
        status:
          type: string
          description: Execution status
          enum:
            - success
            - failure
            - pending
          example: success
        executedAt:
          type: string
          format: date-time
          description: Timestamp when the workflow was executed
          example: "2026-04-19T10:00:00Z"
        duration:
          type: integer
          description: Execution duration in milliseconds
          example: 1200

    WorkflowLogList:
      title: WorkflowLogList
      type: object
      description: List of workflow execution logs
      properties:
        logs:
          type: array
          description: List of log entries
          items:
            $ref: '#/components/schemas/WorkflowLog'

    WorkflowActionRequest:
      title: WorkflowActionRequest
      type: object
      description: Request body for workflow lifecycle actions
      required:
        - workflowId
        - userId
      properties:
        workflowId:
          type: string
          description: Unique identifier of the workflow
          example: "wf_xyz456"
        userId:
          type: string
          description: Identifier of the user
          example: "usr_abc123"

    UpgradeWorkflowRequest:
      title: UpgradeWorkflowRequest
      type: object
      description: Request body for upgrading a workflow
      required:
        - userId
      properties:
        userId:
          type: string
          description: Identifier of the user
          example: "usr_abc123"
        version:
          type: string
          description: Target version to upgrade to
          example: "2.0.0"

    SuccessResponse:
      title: SuccessResponse
      type: object
      description: Standard success response
      properties:
        success:
          type: boolean
          description: Whether the operation succeeded
          example: true
        message:
          type: string
          description: Human-readable success message
          example: "Operation completed successfully"

    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard error response
      properties:
        error:
          type: string
          description: Error code or type
          example: "UNAUTHORIZED"
        message:
          type: string
          description: Human-readable error description
          example: "Invalid API key"