Flowra Triggers API

openapi: 3.2.0
info:
  title: Flowra API (API Key Endpoints) Triggers API
  description: '**Flowra** is an AI-powered platform for building agents, workflows, and integrations.


    ### Capabilities

    - **Tools & Toolkits** – Define and group tools for agents and workflows.

    - **Workflows** – Orchestrate steps and automate processes.

    - **Triggers** – Schedule or event-based execution.

    - **Auth & Connections** – OAuth, API keys, and connected accounts.

    - **MCP** – Model Context Protocol server integration.

    - **Knowledge / RAG** – Add files and URLs for retrieval-augmented generation.


    ### Authentication

    Use the **x-api-key** header with a project API key to access endpoints that support API Key auth. Create and manage API keys in the dashboard under your project settings.


    Only endpoints that support API Key authentication via the @ApiKeyEnabled() decorator.


    Send x-api-key (required). On multi-tenant endpoints, optionally send x-username to act as an external user.'
  version: '1.0'
  contact:
    name: Flowra
    url: https://flowra.dev
servers:
- url: https://flowra.dev
  description: Flowra API
tags:
- name: Triggers
  description: Schedule and event-based trigger instances
paths:
  /api/v1/trigger_instances/{slug}/upsert:
    post:
      operationId: TriggersController_upsertTriggerInstance
      x-apiKeyEnabled: true
      summary: Create or update trigger
      description: Create or update a trigger (e.g. cron schedule or webhook) that runs a workflow automatically. Use the trigger slug to identify the trigger type; pass configuration such as schedule or webhook URL.
      parameters:
      - name: slug
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertTriggerInstanceDto'
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertTriggerInstanceResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  triggerId: 550e8400-e29b-41d4-a716-446655440000
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/trigger_instances/active:
    get:
      operationId: TriggersController_getTriggerInstances
      x-apiKeyEnabled: true
      summary: List active triggers
      description: List your active triggers (scheduled or webhook) with optional filters and pagination. Use to see which workflows are triggered automatically and when.
      parameters:
      - name: q
        required: false
        in: query
        description: Search keyword for filtering results
        schema:
          example: john doe
          type: string
      - name: page
        required: false
        in: query
        description: Page number (1-based)
        schema:
          minimum: 1
          default: 1
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: Number of items per page
        schema:
          minimum: 1
          maximum: 100
          default: 20
          example: 20
          type: number
      - name: offset
        required: false
        in: query
        description: Number of items to skip (for offset-based pagination)
        schema:
          minimum: 0
          example: 0
          type: number
      - name: sortBy
        required: false
        in: query
        description: Field name to sort by
        schema:
          example: createdAt
          type: string
      - name: sortOrder
        required: false
        in: query
        description: Sort order
        schema:
          default: DESC
          example: DESC
          enum:
          - ASC
          - DESC
          type: string
      - name: fields
        required: false
        in: query
        description: Comma-separated list of fields to include in response
        schema:
          example: id,name,email
          type: string
      - name: connectedAccountIds
        required: false
        in: query
        description: Connected account IDs to filter triggers by
        schema:
          type: array
          items:
            type: string
      - name: authConfigIds
        required: false
        in: query
        description: Auth config IDs to filter triggers by
        schema:
          type: array
          items:
            type: string
      - name: trigger_ids
        required: false
        in: query
        description: Trigger instance IDs to filter by (legacy query key)
        schema:
          type: array
          items:
            type: string
      - name: trigger_names
        required: false
        in: query
        description: Trigger tool slugs to filter by (legacy query key)
        schema:
          type: array
          items:
            type: string
      - name: showDisabled
        required: false
        in: query
        description: When true, includes disabled triggers in the response
        schema:
          example: true
          type: boolean
      - name: triggerIds
        required: false
        in: query
        description: Trigger instance IDs to filter by (preferred camelCase)
        schema:
          type: array
          items:
            type: string
      - name: triggerNames
        required: false
        in: query
        description: Trigger tool slugs to filter by (preferred camelCase)
        schema:
          type: array
          items:
            type: string
      - name: deprecatedConnectedAccountUuids
        required: false
        in: query
        description: 'Deprecated: use connectedAccountIds'
        deprecated: true
        schema:
          type: array
          items:
            type: string
      - name: deprecatedAuthConfigUuids
        required: false
        in: query
        description: 'Deprecated: use authConfigIds'
        deprecated: true
        schema:
          type: array
          items:
            type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerInstanceItemDtoPaginatedResponse'
              example:
                success: true
                message: Data retrieved successfully
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  projectId: 550e8400-e29b-41d4-a716-446655440001
                  trigger_name: slack_message_created
                  connected_account_uuid: 550e8400-e29b-41d4-a716-446655440002
                  eUID: user_789
                  trigger_data: '{"webhook_url":"https://example.com/hook"}'
                  triggerConfig:
                    channel: '#general'
                    keywords:
                    - urgent
                  state:
                    status: active
                    last_run: '2023-01-01T00:00:00Z'
                  webhookSecret: a3f1...9c
                  updatedAt: '2023-01-01T00:00:00Z'
                  disabledAt: null
                  connectedAccountId: 550e8400-e29b-41d4-a716-446655440002
                  connectionLabel: sara@company.com
                  triggerName: slack_message_created
                  deprecated:
                    createdAt: ''
                total: 100
                totalTools: 5000
                page: 1
                limit: 20
                totalPages: 5
                hasNextPage: true
                hasPreviousPage: false
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/trigger_instances/invocation-logs:
    get:
      operationId: TriggersController_getTriggerInvocationLogs
      x-apiKeyEnabled: true
      summary: List trigger invocation logs
      description: Unified history of trigger deliveries (connected app, direct webhook, scheduled poll). Scoped to the current project.
      parameters:
      - name: q
        required: false
        in: query
        description: Search keyword for filtering results
        schema:
          example: john doe
          type: string
      - name: page
        required: false
        in: query
        description: Page number (1-based)
        schema:
          minimum: 1
          default: 1
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: Number of items per page
        schema:
          minimum: 1
          maximum: 100
          default: 20
          example: 20
          type: number
      - name: offset
        required: false
        in: query
        description: Number of items to skip (for offset-based pagination)
        schema:
          minimum: 0
          example: 0
          type: number
      - name: sortBy
        required: false
        in: query
        description: Field name to sort by
        schema:
          example: createdAt
          type: string
      - name: sortOrder
        required: false
        in: query
        description: Sort order
        schema:
          default: DESC
          example: DESC
          enum:
          - ASC
          - DESC
          type: string
      - name: fields
        required: false
        in: query
        description: Comma-separated list of fields to include in response
        schema:
          example: id,name,email
          type: string
      - name: toolSlug
        required: false
        in: query
        description: Filter by trigger tool slug
        schema:
          example: slack_receive_message
          type: string
      - name: source
        required: false
        in: query
        description: Filter by how the invocation was received
        schema:
          enum:
          - connected_webhook
          - local_webhook
          - poll_scheduler
          type: string
      - name: triggerId
        required: false
        in: query
        description: Filter rows to a single trigger instance
        schema:
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerInvocationLogListDtoPaginatedResponse'
              example:
                success: true
                message: Data retrieved successfully
                data:
                - id: ''
                  source: connected_webhook
                  sourceLabel: ''
                  toolSlug: ''
                  toolIconUrl: ''
                  triggerInstanceId: ''
                  connectedAccountId: ''
                  projectId: ''
                  euid: ''
                  payload: {}
                  workflowResults:
                  - workflowId: ''
                    workflowName: ''
                    success: true
                    error: ''
                  successful: true
                  error: ''
                  externalLogId: ''
                  metadata: {}
                  invokedAt: '2024-01-01T00:00:00.000Z'
                total: 100
                totalTools: 5000
                page: 1
                limit: 20
                totalPages: 5
                hasNextPage: true
                hasPreviousPage: false
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/trigger_instances/invocation-logs/{logId}/replay-webhook:
    post:
      operationId: TriggersController_replayInvocationWebhook
      x-apiKeyEnabled: true
      summary: Replay trigger invocation as webhook
      description: Re-sends the stored invocation payload through the same webhook pipeline (Composio or local) so workflows run again. Does not execute the trigger tool directly.
      parameters:
      - name: logId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data: {}
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/trigger_instances/manage/{triggerId}:
    delete:
      operationId: TriggersController_deleteTriggerInstanceManage
      x-apiKeyEnabled: true
      summary: Delete trigger
      description: Permanently remove a trigger. The workflow will no longer run on that schedule or webhook.
      parameters:
      - name: triggerId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTriggerInstanceManageResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  triggerId: 550e8400-e29b-41d4-a716-446655440000
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/trigger_instances/manage/{triggerId}/status:
    patch:
      operationId: TriggersController_updateTriggerInstanceStatus
      x-apiKeyEnabled: true
      summary: Enable or disable trigger
      description: Turn a trigger on or off without deleting it. Disabled triggers do not run the workflow until enabled again.
      parameters:
      - name: triggerId
        required: true
        in: path
        schema:
          type: string
      - name: x-username
        in: header
        required: false
        description: External user (end user) to act as. Optional — if omitted, Flowra uses the project’s default external user. Send a stable username (e.g. customer_alice) only when you need another end-user context.
        schema:
          type: string
          default: (project default user)
        example: customer_alice
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusSuccessDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  status: success
      tags:
      - Triggers
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
components:
  schemas:
    TriggerInvocationLogListDtoPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Response message
          example: Data retrieved successfully
        data:
          description: Array of items
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              source:
                enum:
                - connected_webhook
                - local_webhook
                - poll_scheduler
                type: string
              sourceLabel:
                type: string
              toolSlug:
                type: string
              toolIconUrl:
                type:
                - string
                - 'null'
              triggerInstanceId:
                type:
                - string
                - 'null'
              connectedAccountId:
                type:
                - string
                - 'null'
              projectId:
                type:
                - string
                - 'null'
              euid:
                type: string
              payload:
                type:
                - object
                - 'null'
                additionalProperties: true
                description: Trigger event mapped onto the tool output schema (webhook `data`). Transport envelope is not included.
              workflowResults:
                type:
                - array
                - 'null'
                items:
                  type: object
                  properties:
                    workflowId:
                      type: string
                    workflowName:
                      type: string
                    success:
                      type: boolean
                    error:
                      type: string
                  required:
                  - workflowId
                  - success
              successful:
                type: boolean
              error:
                type:
                - string
                - 'null'
              externalLogId:
                type:
                - string
                - 'null'
                description: Omitted on list responses so provider delivery ids are not exposed.
              metadata:
                type:
                - object
                - 'null'
                additionalProperties: true
                description: Omitted on list responses; internal delivery bookkeeping is not exposed.
              invokedAt:
                format: date-time
                type: string
            required:
            - id
            - source
            - sourceLabel
            - toolSlug
            - euid
            - successful
            - invokedAt
          example:
          - id: ''
            source: connected_webhook
            sourceLabel: ''
            toolSlug: ''
            toolIconUrl: ''
            triggerInstanceId: ''
            connectedAccountId: ''
            projectId: ''
            euid: ''
            payload: {}
            workflowResults:
            - workflowId: ''
              workflowName: ''
              success: true
              error: ''
            successful: true
            error: ''
            externalLogId: ''
            metadata: {}
            invokedAt: '2024-01-01T00:00:00.000Z'
        total:
          type: number
          description: Total number of items across all pages
          example: 100
        totalTools:
          type: number
          description: Optional secondary total (e.g. nested tools across all matching toolkits)
          example: 5000
        page:
          type: number
          description: Current page number (1-based)
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 5
        hasNextPage:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there is a previous page
          example: false
      required:
      - success
      - message
      - data
      - total
    DeleteTriggerInstanceManageResponseDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            triggerId:
              type: string
              description: The ID of the deleted trigger instance
              example: 550e8400-e29b-41d4-a716-446655440000
              format: uuid
          required:
          - triggerId
          example:
            triggerId: 550e8400-e29b-41d4-a716-446655440000
      required:
      - success
      - message
      - data
    StatusSuccessDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            status:
              type: string
              example: success
              enum:
              - success
          required:
          - status
          example:
            status: success
      required:
      - success
      - message
      - data
    TriggerInstanceItemDtoPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Response message
          example: Data retrieved successfully
        data:
          description: Array of items
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Trigger instance ID
                example: 550e8400-e29b-41d4-a716-446655440000
              projectId:
                type:
                - string
                - 'null'
                description: Project ID (from user context)
                example: 550e8400-e29b-41d4-a716-446655440001
              trigger_name:
                type: string
                description: Trigger tool slug (same as legacy trigger name)
                example: slack_message_created
              connected_account_uuid:
                type: string
                description: Connected account UUID
                example: 550e8400-e29b-41d4-a716-446655440002
              eUID:
                type: string
                description: User external ID (eUID)
                example: user_789
              trigger_data:
                type: string
                description: Serialized trigger configuration (legacy string form)
                example: '{"webhook_url":"https://example.com/hook"}'
              triggerConfig:
                type: object
                description: Trigger configuration object
                example:
                  channel: '#general'
                  keywords:
                  - urgent
              state:
                type: object
                description: Trigger runtime state / metadata
                example:
                  status: active
                  last_run: '2023-01-01T00:00:00Z'
              webhookSecret:
                type:
                - string
                - 'null'
                description: Shared secret the sender must present when calling POST /webhooks/local/{id}, either as the X-Flowra-Webhook-Secret header or as the key for a Standard Webhooks signature.
                example: a3f1...9c
              updatedAt:
                type: string
                description: Last updated timestamp
                example: '2023-01-01T00:00:00Z'
              disabledAt:
                type:
                - string
                - 'null'
                description: Disabled timestamp
                example: null
              connectedAccountId:
                type: string
                description: Connected account ID (legacy)
                example: 550e8400-e29b-41d4-a716-446655440002
              connectionLabel:
                type:
                - string
                - 'null'
                description: Human label for the connected account (never a UUID)
                example: sara@company.com
              triggerName:
                type: string
                description: Trigger name (legacy)
                example: slack_message_created
              deprecated:
                type: object
                properties:
                  createdAt:
                    type: string
            required:
            - id
            - trigger_name
            - connected_account_uuid
            - eUID
            - trigger_data
            - triggerConfig
            - state
            - webhookSecret
            - updatedAt
            - disabledAt
            - connectedAccountId
            - triggerName
            - deprecated
          example:
          - id: 550e8400-e29b-41d4-a716-446655440000
            projectId: 550e8400-e29b-41d4-a716-446655440001
            trigger_name: slack_message_created
            connected_account_uuid: 550e8400-e29b-41d4-a716-446655440002
            eUID: user_789
            trigger_data: '{"webhook_url":"https://example.com/hook"}'
            triggerConfig:
              channel: '#general'
              keywords:
              - urgent
            state:
              status: active
              last_run: '2023-01-01T00:00:00Z'
            webhookSecret: a3f1...9c
            updatedAt: '2023-01-01T00:00:00Z'
            disabledAt: null
            connectedAccountId: 550e8400-e29b-41d4-a716-446655440002
            connectionLabel: sara@company.com
            triggerName: slack_message_created
            deprecated:
              createdAt: ''
        total:
          type: number
          description: Total number of items across all pages
          example: 100
        totalTools:
          type: number
          description: Optional secondary total (e.g. nested tools across all matching toolkits)
          example: 5000
        page:
          type: number
          description: Current page number (1-based)
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 5
        hasNextPage:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there is a previous page
          example: false
      required:
      - success
      - message
      - data
      - total
    UpsertTriggerInstanceResponseDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            triggerId:
              type: string
              description: ID of the created or updated trigger instance
              example: 550e8400-e29b-41d4-a716-446655440000
              format: uuid
          required:
          - triggerId
          example:
            triggerId: 550e8400-e29b-41d4-a716-446655440000
      required:
      - success
      - message
      - data
    JsonSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          description: Response data
          additionalProperties: true
          example: {}
      required:
      - success
      - message
      - data
    UpsertTriggerInstanceDto:
      type: object
      properties:
        connectedAccountId:
          type: string
          description: ID of the connected account to use for the trigger
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
        triggerConfig:
          type: object
          description: Configuration for the trigger instance
          additionalProperties: true
          example:
            webhook_url: https://myapp.com/webhook
            events:
            - message.created
            - message.updated
            filters:
              channel: '#general'
      required:
      - connectedAccountId
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Project API key. Create and manage keys in the dashboard under Project → API Keys. Send as header: x-api-key: <your-key>'
    x-username:
      type: apiKey
      in: header
      name: x-username
      description: 'Optional. External user username. If omitted, Flowra uses the project’s default external user. Send as header: x-username: <username>'