openapi: 3.2.0
info:
  title: Krosyn Connectors API
  version: 1.0.0
  contact:
    name: Krosyn
  license:
    name: Proprietary
  description: 'Operations tagged Connectors across 2 of this provider''s published API definitions: krosyn-acc-openapi.yaml, krosyn-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
  description: Default API base path
tags:
- name: Connectors
paths:
  /connectors/{connectorId}/trigger:
    post:
      operationId: triggerConnector
      summary: Trigger a connector execution
      description: 'Sends a JSON payload through the connector''s pipeline (Trigger, Process, Perform).


        - If the connector is configured for **async** execution, the request is queued

        and a `202 Accepted` response is returned immediately.

        - If the trigger condition evaluates to false, the connector is **skipped** and

        a `200 OK` response with status `skipped` is returned.

        - On success, a `200 OK` response with the execution result is returned.


        The endpoint is rate-limited via the `throttle:connector-api` middleware.'
      tags:
      - Connectors
      parameters:
      - name: connectorId
        in: path
        required: true
        description: The numeric ID of the connector to trigger.
        schema:
          type: integer
          example: 42
      security:
      - bearerAuth: []
      - secretToken: []
      - customHeaders: []
      requestBody:
        required: true
        description: 'Arbitrary JSON payload that becomes the `$payload` context variable

          in the connector''s expression evaluator. The shape depends on your

          connector configuration.

          '
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Freeform JSON object. Fields are accessible via `$payload.<key>` in expressions.
            examples:
              webhookPayload:
                summary: Webhook event payload
                value:
                  event: order.created
                  customer:
                    name: Jane Doe
                    email: jane@example.com
                  order:
                    id: ORD-12345
                    total: 99.95
                    currency: USD
              simplePayload:
                summary: Simple key-value payload
                value:
                  name: John Doe
                  email: john@example.com
                  action: signup
      responses:
        '200':
          description: Connector executed successfully or skipped.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SuccessResponse'
                - $ref: '#/components/schemas/SkippedResponse'
              examples:
                completed:
                  summary: Successful execution
                  value:
                    success: true
                    message: Connector executed successfully
                    event_id: 1234
                    status: completed
                    response_code: 200
                skipped:
                  summary: Trigger condition not met
                  value:
                    success: true
                    message: Connector trigger condition not met
                    event_id: 1235
                    status: skipped
        '202':
          description: Connector execution queued (async mode).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
              example:
                success: true
                message: Connector execution queued
                async: true
        '400':
          description: Bad request (missing connector ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Connector ID is required
        '401':
          description: Authentication failed (missing or invalid token, expired token, or invalid webhook signature).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingToken:
                  summary: No authentication provided
                  value:
                    error: Bearer token or secret token is required
                invalidToken:
                  summary: Invalid credentials
                  value:
                    error: Invalid authentication token
                expiredToken:
                  summary: Expired credentials
                  value:
                    error: Authentication token has expired
                invalidSignature:
                  summary: Webhook signature mismatch
                  value:
                    error: Invalid webhook signature
        '403':
          description: Forbidden (connector is disabled, or origin not allowed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                disabled:
                  summary: Connector not enabled
                  value:
                    error: Connector is not enabled
                originBlocked:
                  summary: Origin validation failed
                  value:
                    error: Origin not allowed
        '404':
          description: Connector or endpoint not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Connector not found
        '429':
          description: Rate limit or subscription quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Monthly operations limit exceeded
        '500':
          description: Connector execution failed or internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResponse'
              examples:
                executionFailed:
                  summary: Perform phase failed
                  value:
                    success: false
                    message: Connector execution failed
                    event_id: 1236
                    status: failed
                    response_code: 502
                internalError:
                  summary: Unexpected server error
                  value:
                    error: Internal server error
                    message: An error occurred
    servers:
    - url: /api/v1
      description: Default API base path
components:
  schemas:
    FailedResponse:
      type: object
      required:
      - success
      - message
      - event_id
      - status
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Connector execution failed
        event_id:
          type: integer
          example: 1236
        status:
          type: string
          enum:
          - failed
          example: failed
        response_code:
          type: integer
          description: HTTP status code from the failed outbound request.
          example: 502
    SkippedResponse:
      type: object
      required:
      - success
      - message
      - event_id
      - status
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Connector trigger condition not met
        event_id:
          type: integer
          example: 1235
        status:
          type: string
          enum:
          - skipped
          example: skipped
    SuccessResponse:
      type: object
      required:
      - success
      - message
      - event_id
      - status
      - response_code
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Connector executed successfully
        event_id:
          type: integer
          description: ID of the ConnectorEvent record.
          example: 1234
        status:
          type: string
          enum:
          - completed
          example: completed
        response_code:
          type: integer
          description: HTTP status code from the outbound perform request.
          example: 200
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Invalid authentication token
        message:
          type: string
          description: Additional detail (only in debug mode for 500 errors).
          example: Connection refused
    AsyncResponse:
      type: object
      required:
      - success
      - message
      - async
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Connector execution queued
        async:
          type: boolean
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token authentication. The token must match the `bearer_token`

        stored on the connector''s endpoint record.

        '
    secretToken:
      type: apiKey
      in: header
      name: X-Secret-Token
      description: 'Secret token authentication. The value must match the `secret_token`

        stored (encrypted at rest) on the connector''s endpoint record.

        '
    customHeaders:
      type: apiKey
      in: header
      name: X-Custom-Auth
      description: 'Custom header authentication. The connector endpoint can store a JSON

        map of header-name to expected-value pairs. Any matching header

        authenticates the request. The actual header name varies per connector.

        '
x-refined-from:
- krosyn-acc-openapi.yaml
- krosyn-openapi.yaml